RAG 知识库问答系统Agent

把任意文档（txt / md / pdf）变成一个只依据你的资料回答、不瞎编的 AI 问答机器人。上传一份手册 → 提问 → AI 基于文档内容作答并标注来源；问到资料外的内容，会老实回答「无法回答」。

适用场景：企业知识库问答、智能客服、产品手册 / 操作文档问答、公司内部制度问答。

核心特性

落地 AI 客服最怕两件事：答不准和一本正经地胡说八道。本项目用 RAG（检索增强生成）正面解决这两点：

#zFcqvGbIIDfV text { white-space: pre; }#zFcqvGbIIDfV .fb0 { stroke: var(--N900-FG, 0.15); }#zFcqvGbIIDfV .fb0 {stroke: rgba(31,35,41, 0.15)}#zFcqvGbIIDfV .fx0 { stroke-miterlimit: 10; }#zFcqvGbIIDfV .fx0 {stroke-miterlimit: 10}#zFcqvGbIIDfV .fa1 { fill: rgb(187, 191, 196); }#zFcqvGbIIDfV .fa1 {fill: rgb(187, 191, 196)}#zFcqvGbIIDfV .fx1 { font: 400 12px MonospacedNumber, LarkHackSafariFont, LarkEmojiFont, LarkChineseQuote, -apple-system, BlinkMacSystemFont, "Helvetica Neue", Tahoma, "PingFang SC", "Microsoft Yahei", Arial, "Hiragino Sans GB", sans-serif, "Apple Color Emoji", "Segoe UI Emoji", "Segoe UI Symbol", "Noto Color Emoji"; }#zFcqvGbIIDfV .fx1 {font-style: normal}#zFcqvGbIIDfV .fx2 { text-anchor: middle; }#zFcqvGbIIDfV .fx2 {text-anchor: middle}#zFcqvGbIIDfV .fx3 { dominant-baseline: central; }#zFcqvGbIIDfV .fx3 {dominant-baseline: central}#zFcqvGbIIDfV .fx4 { stroke: none; }#zFcqvGbIIDfV .fx4 {stroke: none}#zFcqvGbIIDfV .fc0 { fill: var(--text-caption); }#zFcqvGbIIDfV .fc0 {fill: #646a73}#zFcqvGbIIDfV .fa2 { fill: var(--text-link-disabled); }#zFcqvGbIIDfV .fa2 {fill: rgb(187, 191, 196)}#zFcqvGbIIDfV .fx5 { font: 400 13px MonospacedNumber, LarkHackSafariFont, LarkEmojiFont, LarkChineseQuote, -apple-system, BlinkMacSystemFont, "Helvetica Neue", Tahoma, "PingFang SC", "Microsoft Yahei", Arial, "Hiragino Sans GB", sans-serif, "Apple Color Emoji", "Segoe UI Emoji", "Segoe UI Symbol", "Noto Color Emoji"; }#zFcqvGbIIDfV .fx5 {font-style: normal}#zFcqvGbIIDfV .fx6 { text-anchor: start; }#zFcqvGbIIDfV .fx6 {text-anchor: start}#zFcqvGbIIDfV .fx7 { dominant-baseline: alphabetic; }#zFcqvGbIIDfV .fx7 {dominant-baseline: alphabetic}#zFcqvGbIIDfV .fc1 { fill: rgb(0, 0, 0); }#zFcqvGbIIDfV .fc1 {fill: rgb(0, 0, 0)}#zFcqvGbIIDfV .fb1 { fill: var(--N900-FG, 0.15); }#zFcqvGbIIDfV .fb1 {fill: rgba(31,35,41, 0.15)}#zFcqvGbIIDfV .fb2 { fill: rgb(209, 217, 224); }#zFcqvGbIIDfV .fb2 {fill: rgb(209, 217, 224)}#zFcqvGbIIDfV .fa3 { fill: var(--bg-body); }#zFcqvGbIIDfV .fa3 {fill: #fff}ABC123特性答得准（带来源）不瞎编（资料外答"无法回答"）做法先在文档里检索最相关的段落，再让大模型据此回答，并把依据的来源段落 + 相关度一起返回系统提示强制「只能依据参考资料回答，资料里没有就如实说不知道」，并配合低温度采样价值答案可追溯、可核对，不是黑盒杜绝幻觉，可放心接入客服场景

演示

飞书文档 - 图片

上传示例文档-星辰科技员工手册.md，左侧「已入库文档」刷新。

提问文档内的问题（如「年假有几天？」）：返回准确答案，并在下方标注来源段落与相关度。

提问文档外的问题（如「公司在哪上市？」）：返回「根据现有资料，我无法回答这个问题。」

架构 / RAG 流程

代码块

SQL

flowchart LR

subgraph 建库["① 建库（上传文档时）"]

A[原始文档
txt / md / pdf] --> B[切分 chunk
400 字 + 80 重叠]

B --> C[本地 Embedding
bge-small-zh]

C --> D[(Chroma
向量库)]

end

subgraph 问答["② 问答（用户提问时）"]

Q[用户问题] --> QE[问题向量化]

QE --> R[向量检索
余弦相似度 Top-K]

D --> R

R --> P[拼接参考资料 + 问题]

P --> LLM[DeepSeek
据资料作答]

飞书文档 - 图片

6. 快速启动

先选择运行模式，再准备环境变量。两种模式不要混用。

#fAXRuuHmpTCJ text { white-space: pre; }#fAXRuuHmpTCJ .fb0 { stroke: var(--N900-FG, 0.15); }#fAXRuuHmpTCJ .fb0 {stroke: rgba(31,35,41, 0.15)}#fAXRuuHmpTCJ .fx0 { stroke-miterlimit: 10; }#fAXRuuHmpTCJ .fx0 {stroke-miterlimit: 10}#fAXRuuHmpTCJ .fa1 { fill: rgb(187, 191, 196); }#fAXRuuHmpTCJ .fa1 {fill: rgb(187, 191, 196)}#fAXRuuHmpTCJ .fx1 { font: 400 12px MonospacedNumber, LarkHackSafariFont, LarkEmojiFont, LarkChineseQuote, -apple-system, BlinkMacSystemFont, "Helvetica Neue", Tahoma, "PingFang SC", "Microsoft Yahei", Arial, "Hiragino Sans GB", sans-serif, "Apple Color Emoji", "Segoe UI Emoji", "Segoe UI Symbol", "Noto Color Emoji"; }#fAXRuuHmpTCJ .fx1 {font-style: normal}#fAXRuuHmpTCJ .fx2 { text-anchor: middle; }#fAXRuuHmpTCJ .fx2 {text-anchor: middle}#fAXRuuHmpTCJ .fx3 { dominant-baseline: central; }#fAXRuuHmpTCJ .fx3 {dominant-baseline: central}#fAXRuuHmpTCJ .fx4 { stroke: none; }#fAXRuuHmpTCJ .fx4 {stroke: none}#fAXRuuHmpTCJ .fc0 { fill: var(--text-caption); }#fAXRuuHmpTCJ .fc0 {fill: #646a73}#fAXRuuHmpTCJ .fa2 { fill: var(--text-link-disabled); }#fAXRuuHmpTCJ .fa2 {fill: rgb(187, 191, 196)}#fAXRuuHmpTCJ .fc1 { stroke: var(--B500); }#fAXRuuHmpTCJ .fc1 {stroke: #336df4}#fAXRuuHmpTCJ .fx5 { font: 400 13px MonospacedNumber, LarkHackSafariFont, LarkEmojiFont, LarkChineseQuote, -apple-system, BlinkMacSystemFont, "Helvetica Neue", Tahoma, "PingFang SC", "Microsoft Yahei", Arial, "Hiragino Sans GB", sans-serif, "Apple Color Emoji", "Segoe UI Emoji", "Segoe UI Symbol", "Noto Color Emoji"; }#fAXRuuHmpTCJ .fx5 {font-style: normal}#fAXRuuHmpTCJ .fx6 { text-anchor: start; }#fAXRuuHmpTCJ .fx6 {text-anchor: start}#fAXRuuHmpTCJ .fx7 { dominant-baseline: alphabetic; }#fAXRuuHmpTCJ .fx7 {dominant-baseline: alphabetic}#fAXRuuHmpTCJ .fc2 { fill: rgb(0, 0, 0); }#fAXRuuHmpTCJ .fc2 {fill: rgb(0, 0, 0)}#fAXRuuHmpTCJ .fx8 { font: 400 13px LarkHackSafariFont, LarkEmojiFont, ui-monospace, -apple-system, BlinkMacSystemFont, "Helvetica Neue", Helvetica, "Noto Sans", Tahoma, "Nimbus Sans L", Arial, "Liberation Sans", "PingFang SC", "Hiragino Sans GB", "Noto Sans CJK SC", "Source Han Sans SC", "Source Han Sans CN", "Microsoft YaHei", "Wenquanyi Micro Hei", "WenQuanYi Zen Hei", STHeiti, SimHei, sans-serif, "Apple Color Emoji", "Segoe UI Emoji", "Segoe UI Symbol", "Noto Color Emoji", system-ui; }#fAXRuuHmpTCJ .fx8 {font-style: normal}#fAXRuuHmpTCJ .fc3 { fill: var(--B500); }#fAXRuuHmpTCJ .fc3 {fill: #336df4}#fAXRuuHmpTCJ .fb1 { fill: var(--N900-FG, 0.15); }#fAXRuuHmpTCJ .fb1 {fill: rgba(31,35,41, 0.15)}#fAXRuuHmpTCJ .fb2 { fill: rgb(209, 217, 224); }#fAXRuuHmpTCJ .fb2 {fill: rgb(209, 217, 224)}#fAXRuuHmpTCJ .fa3 { fill: var(--bg-body); }#fAXRuuHmpTCJ .fa3 {fill: #fff}ABC12345文件是否提交是否是否用途Docker Compose 模板，地址使用、、Docker Compose 实际运行配置，由复制后填写本机 API 调试模板，地址使用和本机 API 实际运行配置，由复制后填写.env.compose.example.env.compose.env.local.example.envmysqlmilvus/app/models/....env.compose.examplemodels/....env.local.examplelocalhost

项目不再保留 .env.example。这个名字无法表达运行模式，容易把容器地址和本机地址混用。

6.1 全 Docker 测试

当前如果只是为了验收项目，推荐让 MySQL、Milvus 和 API 都由 Docker Compose 管理。这样 API 容器访问依赖时统一使用 mysql、milvus 这些 Compose 服务名，不会和宿主机 localhost 视角混在一起。

代码块

JavaScript

if (!(Test-Path .env.compose)) { Copy-Item .env.compose.example .env.compose }

notepad .env.compose

必须配置真实可用值：

代码块

Plain Text

DASHSCOPE_API_KEY=真实可用的模型服务 Key

ADMIN_API_TOKEN=随机长令牌

一键部署当前 active 场景：

代码块

JavaScript

.\scripts\deploy_docker.ps1

如果要一次性初始化 8 个冻结业务场景：

代码块

JavaScript

.\scripts\deploy_docker.ps1 -AllScenarios

脚本执行顺序是：启动 MySQL/Milvus → 构建 API 镜像 → 在 API 容器里重建并激活知识库 → 启动 API。这个顺序不能反过来，因为 API 启动前会检查 active KB 版本；空库直接启动 API 会被 preflight 拒绝。

脚本也会提前创建 logs/、reports/ 两个运行时目录。手动执行 docker compose 时也要保证这些目录存在，否则 Windows Docker 可能把缺失的宿主机目录挂成不可用路径。

手动执行等价命令：

代码块

JavaScript

docker compose --env-file .env.compose up -d mysql etcd minio milvus

docker compose --env-file .env.compose build api

docker compose --env-file .env.compose run --rm api python scripts/rebuild_kb_version.py --scenario enterprise_knowledge --new-version --force --quality-gate --activate

docker compose --env-file .env.compose up -d api

docker compose --env-file .env.compose ps

讲义和流程动画由宿主机 ./site 挂载到容器 /app/site。修改 docs/ 或 docs/animation/ 后，先执行 python -m mkdocs build，刷新 /project-docs/... 即可看到更新；不需要为了讲义内容重建 API 镜像。

6.2 本机 API 调试

本机启动 API，Docker 只跑 MySQL/Milvus：

代码块

JavaScript

if (!(Test-Path .env)) { Copy-Item .env.local.example .env }

notepad .env

本机模式同样必须配置真实可用值：

代码块

Plain Text

DASHSCOPE_API_KEY=真实可用的模型服务 Key

ADMIN_API_TOKEN=随机长令牌

DASHSCOPE_API_KEY 不是形式校验。服务启动前会实际调用一次 OpenAI-compatible LLM 接口，Key 欠费、无权限、模型名错误或服务地址不可用都会直接启动失败。正式学习和演示前请先运行 python scripts/check_langchain_stack.py，确认模型服务可用。

LangSmith 是企业观测和评测主入口，但本地教学 smoke 不强制开启。未配置 LANGSMITH_TRACING=true 和 LANGSMITH_API_KEY 时，状态页会显示未启用，接口验收仍会通过；正式企业化演示时再打开 LangSmith tracing。

本地模型必须存在：

代码块

Plain Text

models/bge-m3

models/bge-reranker-large

启动基础设施：

代码块

JavaScript

docker compose --env-file .env.compose up -d mysql etcd minio milvus

在宿主机启动 API：

代码块

JavaScript

python -m uvicorn app:app --host 127.0.0.1 --port 8000

检查 LangChain、Milvus、MySQL、模型和 LLM 配置：

代码块

JavaScript

python scripts/check_langchain_stack.py

7. 初始化知识库

Docker Compose 模式下，推荐在 API 容器内执行入库脚本。所有 docker compose --env-file .env.compose ... 命令都要求项目根目录已经存在 .env.compose，仓库只提交 .env.compose.example，首次使用前先生成本地配置文件：

代码块

JavaScript

if (!(Test-Path .env.compose)) { Copy-Item .env.compose.example .env.compose }

notepad .env.compose

新环境首次部署，或者 Milvus collection schema 变更后需要重建全部 8 个冻结场景，使用：

代码块

JavaScript

docker compose --env-file .env.compose up -d mysql etcd minio milvus

docker compose --env-file .env.compose build api

docker compose --env-file .env.compose run --rm api python scripts/rebuild_scenarios.py --reset-collections

如果之前已经存在知识库，只是资料内容变化，重建全部 8 个场景时不要删除 collection：

代码块

JavaScript

如果只重建某一个已有场景，例如企业知识场景：

代码块

JavaScript

docker compose --env-file .env.compose run --rm api python scripts/rebuild_kb_version.py --scenario enterprise_knowledge --new-version --force --quality-gate --activate

只有在旧 collection schema 不兼容、切换了 hybrid 字段结构，或者明确要清空重建单场景 collection 时，才给单场景命令追加 --reset-collections：

代码块

JavaScript

docker compose --env-file .env.compose run --rm api python scripts/rebuild_kb_version.py --scenario enterprise_knowledge --new-version --force --reset-collections --quality-gate --activate

本机 API 调试模式下，首次运行或资料变更后，重建并激活 8 个场景：

代码块

Bash

$scenarios = 'enterprise_knowledge','saas_support','equipment_ops','compliance_qa','cross_border_risk','tender_contract_risk','insurance_claims','engineering_project_qa'

foreach ($s in $scenarios) {

python scripts/rebuild_kb_version.py --scenario $s --new-version --force --quality-gate --activate

}

单独重建某个场景：

代码块

JavaScript

python scripts/rebuild_kb_version.py --scenario engineering_project_qa --new-version --force --quality-gate --activate

8. 验收命令

代码与守护检查：

代码块

JavaScript

python -m compileall app.py qa_core scripts tests

python -m pytest tests -q

python scripts/check_project_guardrails.py

最小闭环命令只需要记住这几条：

代码块

Bash

python scripts/rebuild_kb_version.py --scenario enterprise_knowledge --new-version --force --quality-gate --activate

python scripts/evaluate_core_chain.py --dataset eval_sets/multi_scenario_smoke.json --limit 20 --output reports/evaluation/multi_scenario_smoke_live.json

python scripts/check_evaluation_gate.py --report reports/evaluation/multi_scenario_smoke_live.json

多场景核心评测：

代码块

JavaScript

python scripts/evaluate_core_chain.py --dataset eval_sets/multi_scenario_smoke.json --limit 40 --output reports/evaluation/multi_scenario_smoke_live_40.json

python scripts/check_evaluation_gate.py --report reports/evaluation/multi_scenario_smoke_live_40.json

面试增强评测：

代码块

JavaScript

python scripts/evaluate_core_chain.py --dataset eval_sets/multi_scenario_interview_regression.json --limit 16 --output reports/evaluation/multi_scenario_interview_regression_live_16_final.json

python scripts/check_evaluation_gate.py --report reports/evaluation/multi_scenario_interview_regression_live_16_final.json --min-source-inference-accuracy 1.0 --min-prompt-profile-accuracy 1.0

业务深度评测：

代码块

JavaScript

python scripts/evaluate_core_chain.py --dataset eval_sets/business_depth_regression.json --limit 32 --output reports/evaluation/business_depth_regression_live_32.json

python scripts/check_evaluation_gate.py --report reports/evaluation/business_depth_regression_live_32.json --min-source-inference-accuracy 1.0 --min-prompt-profile-accuracy 0.85

多轮追问评测：

代码块

JavaScript

python scripts/evaluate_followup_chain.py --dataset eval_sets/multi_turn_followup_regression.json --output reports/evaluation/multi_turn_followup_smoke.json

真实链路验收：

如果 API 在 Docker Compose 中运行，推荐在 API 容器内执行验收脚本，脚本会读取 .env.compose 注入的 ADMIN_API_TOKEN，不需要把管理令牌写在命令行里。

真实 API 合同验收：

代码块

JavaScript

docker compose --env-file .env.compose exec api python scripts/api_e2e_smoke.py --base-url http://127.0.0.1:8000

该脚本只检查 LangSmith 状态接口是否可用，不要求本地环境必须开启 LangSmith。是否开启会写入 details.langsmith_enabled，方便正式演示前确认。

页面和 WebSocket 验收：

代码块

JavaScript

docker compose --env-file .env.compose exec api python scripts/acceptance_smoke.py --base-url http://127.0.0.1:8000

项目里不再保留“一键发布检查”概念，避免把质量证明和脚本编排混在一起。需要证明质量时，按上面的入库质量检查、RAG 回归验收、接口验收脚本分别执行即可。

OCR 复核资料提升：

代码块

Bash

python scripts/ocr/run_offline_ocr.py --input-dir incoming_scans --output-dir reports/ocr/batch_001

python scripts/ocr/promote_ocr_candidates.py --input-dir reports/ocr/batch_001 --scenario engineering_project_qa --source quality

python scripts/ocr/promote_ocr_candidates.py --input-dir reports/ocr/batch_001 --scenario engineering_project_qa --source quality --apply

python scripts/rebuild_kb_version.py --scenario engineering_project_qa --new-version --force --quality-gate --activate

固定性能基线：

代码块

JavaScript

python scripts/check_performance_gate.py --dataset eval_sets/phase1_performance_baseline.json --limit 8 --no-warmup --output reports/verification/phase1_performance_latest.json --gate-output reports/verification/phase1_performance_gate_latest.json

全场景版本召回对比：

代码块

JavaScript

python scripts/kb/compare_all_kb_versions.py --dataset eval_sets/business_depth_regression.json --per-scenario-limit 2 --output reports/verification/kb_version_compare_all_latest.json

缺失文档清理预览：

代码块

JavaScript

python scripts/cleanup_missing_docs.py --all-scenarios

如果报告确认无误，再显式执行：

代码块

JavaScript

python scripts/cleanup_missing_docs.py --all-scenarios --apply

Bad Case 反馈闭环统一交给 LangSmith：

代码块

Plain Text

Trace 过滤异常样本

-> Annotation 标注 expected_hit_type / expected_source / expected_keywords

-> Dataset 沉淀真实线上回归样本

-> Evaluation 运行领域指标

-> 变更前后对比关键结果

本项目不再维护本地 Bad Case 导出、复核队列和提升脚本。代码重点放在 RAG 主链路、source 推断、权限过滤、知识库版本、FAQ 命中、Prompt Profile、检索后处理和领域评测指标。

本地通电诊断：

python scripts/tools/check_local_runtime.py --require-api --output reports/verification/local_runtime_latest.json

这份诊断报告现在不只会告诉你“端口不通”，还会额外说明三件事：

•

当前 .env 是否符合“本机 API + localhost 端口”模式；

•

docker-compose.yml 和 docker-compose.milvus.yml 分别暴露了哪些宿主机端口；

•

docker ps 里是否已经有相关容器存在，但没有把 MySQL / Milvus / API 端口映射到宿主机。

如果 .env 使用 mysql、milvus 和 /app/models/...，通常说明把 Compose 配置复制到了本机 API 调试配置里。宿主机直接跑诊断时，脚本会把这些容器内视角的端口和路径降级为提示项，避免把 “运行模式不同”误判成项目不可用。全 Docker 模式请检查 .env.compose，并优先在 API 容器内执行验收命令。

例如当前仓库里，标准 docker-compose.yml 默认把 MySQL 暴露到 3306，而 docker-compose.milvus.yml 把 MySQL 暴露到 3307。如果本机 .env 写的是 MYSQL_PORT=3307，但你实际启动的是标准 docker-compose.yml 那套服务，诊断报告会明确指出是本机配置与容器端口不一致，而不是只给出一个抽象的“连接失败”。

企业资料真实度分析：

代码块

JavaScript

python scripts/enterprise_overlay/analyze_enterprise_data_realism.py --output reports/verification/enterprise_data_realism_latest.json

当前 scenarios/ 是可控教学样本。企业仿真数据包位于 data_packs/enterprise_realistic_pack/，其中 clean_overlay/ 可用于后续入库增强，dirty_samples/ 只用于资料治理演示，不默认进入 active 知识库版本。详细说明见 enterprise_data_realism.md。

clean overlay 预检：

代码块

JavaScript

这会在 reports/enterprise_overlay_build/ 下生成临时增强数据集，并复用入库质量报告和入库质量检查。它只验证“增强资料是否具备进入知识库版本重建的资格”，不会修改当前 active 知识库。

dirty samples 治理分析：

代码块

JavaScript

python scripts/enterprise_overlay/analyze_dirty_enterprise_samples.py --output reports/verification/dirty_enterprise_samples_latest.json

它会识别过期口径、FAQ/正文冲突风险、OCR 噪声和表格专用切分需求，并明确这些样本默认不允许 active 入库。

企业 overlay 就绪检查：

代码块

JavaScript

它会确认 clean overlay 预检、dirty samples 阻断、资料真实度提升和 overlay 回归评测集覆盖都满足要求。

生成 overlay 上线计划：

代码块

JavaScript

python scripts/enterprise_overlay/plan_enterprise_overlay_activation.py --output reports/verification/enterprise_overlay_activation_plan_latest.json

计划文件只生成 rebuild_kb_version.py 命令。需要正式执行计划时，运行：

代码块

JavaScript

python scripts/enterprise_overlay/run_enterprise_overlay_activation.py --plan reports/verification/enterprise_overlay_activation_plan_latest.json --output reports/verification/enterprise_overlay_activation_run_latest.json

增强资料真正激活后，再跑：

代码块

JavaScript

python scripts/check_evaluation_gate.py --dataset eval_sets/enterprise_overlay_regression.json --limit 24 --output reports/verification/enterprise_overlay_evaluation_latest.json --gate-output reports/verification/enterprise_overlay_evaluation_gate_latest.json --min-source-inference-accuracy 1.0 --min-prompt-profile-accuracy 0.85

这条 overlay 回归作为独立质量检查保留，适合临时排查或资料增强后快速复测。

该报告现在会优先读取最新 live 验收产物，而不是旧的静态报告快照，重点汇总：

•

最新业务深度评测；

•

最新多轮追问评测；

•

最新性能回归结果；

•

最新企业资料真实度、clean overlay 预检和 dirty samples 治理摘要；

•

当前 bad case 复核分层；

•

当前本地通电状态。

这轮又补了两类状态页筛选能力：

•

时间窗口：最近 30m / 6h / 24h / 7d / 全部时间

•

定位维度：按 closure_bucket / session_id / trace_id 聚焦 bad case 和 trace

现在状态页不只是“看报表”，而是可以直接回答：

•

这次新增问题是最近 24 小时出现的，还是旧历史遗留；

•

某次验收会话里到底是哪条 trace 开始回答变差；

•

这是边界拦截本来就对，还是知识覆盖真的缺了。

9. 当前验证结果

最近一次业务深度回归：

代码块

Plain Text

reports/evaluation/business_depth_regression_live_32.json

关键指标：

代码块

Plain Text

total = 32

errors = 0

recall_at_k = 1.0

mrr = 1.0

hit_type_accuracy = 1.0

source_inference_accuracy = 1.0

prompt_profile_accuracy = 1.0

faq_direct_accuracy = 1.0

scenario_isolation_accuracy = 1.0

avg_keyword_coverage = 0.9922

项目守护检查已覆盖：

•

禁止恢复旧版 mysql_qa / rag_qa 主链路；

•

禁止新增第 9 个场景包；

•

禁止 fallback 导入和技术降级路径；

•

检查依赖锁、导入位置和密钥卫生。

10. 推荐演示问题

演示时建议打开 /admin，观察命中的 scenario_id、source_filter、kb_version、prompt_profile、来源引用和阶段耗时。

11. 文档导航

12. 二期方向

一期只做 RAG，并且已经闭环：

•

知识库构建；

•

多场景检索；

•

FAQ + 文档混合；

•

多版本；

•

数据隔离；

•

流式问答；

•

入库质量检查；

•

评测回归。

二期再引入 Agent，不把 Agent 能力混入一期主链路。二期适合做：

•

LangGraph 工作流；

•

Router/Planner 统一调度；

•

GraphRAG Agent 关系推理；

•

SQL Agent 结构化查询；

•

Workflow Agent 审批/工单流程；

•

Skill Registry；

•

Agent 任务状态机；

•

工具权限分级；

•

人工确认与审计；

•

Agent Trace 和 Agent 回归验收；

•

模型路由与成本治理；

•

A2A 跨 Agent 协作协议适配；

•

MCP 外部工具/资源接入适配；

•

工具调用；

•

审批/工单/核查流程模拟；

•

风险处置步骤编排；

•

多角色协同。

后续增强层不抢二期首版主线：

•

多模态入库：复杂 PDF、扫描件、图纸、票据、验收照片，先解析、复核、质检，再版本化入库；

•

GraphRAG：只用于合同、理赔、工程规范这类关系链明显的问题，不替代当前 Milvus Hybrid RAG；

•

模型升级实验：在 bge-m3 基线稳定后，再评估 Qwen3-Embedding 等新模型。

二期工程治理重点：

•

Skill、Prompt、Tool Policy、模型路由和知识库版本都要能灰度和回滚；

•

高风险任务必须进入人工确认；

•

Trace、A2A 消息、Agent Card 和报告都要做敏感信息脱敏；

•

长任务要支持状态查询、取消和失败恢复。

13. 安全说明

•

.env、.env.compose 不提交真实 Key；

•

.env.local.example、.env.compose.example 只保留占位符；

•

logs/、reports/ 默认不作为线上公开材料；

•

当前项目不提供技术降级方案，Milvus、MySQL、本地模型、LLM Key 和 active 知识库版本都是启动前置条件。

目录结构

代码块

Plain Text

rag-demo/

├── app/

│ ├── main.py # FastAPI 接口 + 托管前端

│ ├── rag.py # RAG 核心：切分 → 向量化 → 检索 → 生成

│ └── static/index.html # 前端页面（原生 HTML/JS，无需构建）

├── data/

│ ├── docs/ # 上传的原始文档

│ └── chroma/ # 向量库（自动生成）

├── 示例文档-星辰科技员工手册.md

技术栈

可拓展方向

•

接入微信公众号 / 企业微信 / 飞书机器人

•

支持更多格式：Word、Excel、网页抓取

•

多轮对话记忆与对话历史

•

来源高亮，跳转回原文位置

•

流式输出（SSE）、检索重排序（rerank）提升精度