面向研发文档和故障案例的可追溯 RAG Agent，提供多格式摄取、混合检索、 带引用问答、有界排障 Agent、Trace/Replay 与离线评测。
flowchart LR
UI[React Console] --> API[FastAPI]
API --> ACL[JWT + document ACL]
API --> ING[Parser + Chunker]
API --> RET[Dense + Sparse + RRF]
RET --> RR[Optional Reranker]
API --> RAG[RAG + Citation Guard]
API --> AG[Bounded 4-tool Agent]
RAG --> LLM[OpenAI-compatible LLM]
AG --> LLM
ING --> PG[(PostgreSQL)]
API --> PG
ING --> QD[(Qdrant)]
RET --> QD
上传请求经过解析、标题感知分块、Dense/Sparse Embedding 后同时写入 PostgreSQL
和 Qdrant。查询在召回前合并 Metadata Filter 与 ACL，执行 Dense/Sparse 检索、
RRF 融合和可选 Rerank；RAG 只向 LLM 提供预算内证据，并校验回答中的引用编号。
request_id 关联响应、消息、检索阶段、Prompt、Token 用量、工具调用及 Replay。
详细流程见 architecture.md。
- Markdown、PDF、HTML、JSON、TXT 解析和目录批量导入
- SHA-256 去重、文档级更新/重建/删除一致性和摄取耗时
- BGE Dense + Qdrant/BM25 Sparse + RRF，可选 Cross-Encoder Rerank
- 项目、版本、模块、文档类型、状态 Filter 与
public/private/groupACL - JSON/SSE 引用问答、无依据拒答、一次引用修复和会话摘要
- 4 工具、最多 5 次调用的排障 Agent
- Query Rewrite、各检索阶段、Prompt、Token、延迟与工具调用 Trace/Replay
- Dense、Hybrid、Hybrid + Rerank 离线评测及 PostgreSQL 运行记录
- React 文档、问答、Agent、Trace 和 Eval 调试台
非目标：通用工作流编排、跨用户画像、复杂长期记忆、OCR 和生产级身份管理后台。
要求 Docker Desktop。复制配置并填写 LLM Key：
Copy-Item .env.example .env
# 编辑 .env 中的 TECHRAG_LLM_API_KEY
docker compose up --build打开 http://localhost:5173。API、OpenAPI 和 Qdrant 控制台分别位于
http://localhost:8000、http://localhost:8000/docs 和
http://localhost:6333/dashboard。
首次摄取会下载 Embedding 模型，首次 Rerank 会下载 Cross-Encoder；模型缓存由
Docker volume 持久化。修改 .env 后需执行 docker compose up -d --force-recreate api
使容器重新加载配置。
| Variable | Purpose | Default |
|---|---|---|
TECHRAG_LLM_API_KEY |
OpenAI 兼容 LLM 密钥 | 空，问答生成不可用 |
TECHRAG_LLM_BASE_URL |
LLM API 地址 | https://api.deepseek.com |
TECHRAG_LLM_MODEL |
Chat Completions 模型 | deepseek-chat |
TECHRAG_DATABASE_URL |
PostgreSQL async URL | Compose 内部 postgres:5432 |
TECHRAG_QDRANT_URL |
Qdrant URL | Compose 内部 qdrant:6333 |
TECHRAG_RERANKER_ENABLED |
是否启用 Rerank | true |
TECHRAG_RAG_CONTEXT_MAX_CHARS |
证据字符预算 | 24000 |
TECHRAG_MEMORY_COMPACTION_THRESHOLD |
摘要触发消息数 | 12 |
TECHRAG_JWT_SECRET |
JWT 签名密钥 | 仅开发默认值 |
全部配置及模型名见 .env.example。生产环境必须更换 JWT Secret 并 携带 Bearer Token；开发环境未提供 Token 时使用固定管理员身份。
主线之外提供一套并排的 LangGraph 实现（backend/langchain_app/），复用全部
领域层（检索、LLM、ACL、Trace、DB），仅把编排切换为 LangGraph StateGraph：
POST /api/v2/chat：RAG 流程节点化为 改写 -> 检索 -> 证据预算 -> 生成 -> 引用校验 -> 一次性修复 -> 二次校验（backend/langchain_app/rag/graph.py）POST /api/v2/agent/troubleshoot：排障 Agent 固定 DAG 节点化 search -> section -> [compare] -> plan，条件边处理版本对比与无证据拒答 （backend/langchain_app/agent/graph.py）
设计取舍：检索与 LLM 调用刻意保留自研领域层（ACL 贯穿、阶段 Trace、引用约束）， LangGraph 只负责表达流程态；这与引入现成 RAG chain 相比，保留了可追溯性且便于 在评测集上做 A/B 对比。LangGraph 未随应用主线强制依赖，缺失时 v2 路由自动降级。
以下示例假定已创建知识库并将 ID 保存为 $KB_ID。
上传文档：
curl.exe -X POST "http://localhost:8000/api/v1/knowledge-bases/$KB_ID/documents" `
-F "file=@data/corpus/worker-guide.md" `
-F "project=techrag" -F "version=2.1" -F "module=worker" `
-F "document_type=guide" -F "visibility=private"混合检索：
$body = @{knowledge_base_id=$KB_ID; query='tool timeout'; mode='hybrid';
filters=@{project='techrag'; version='2.1'}} | ConvertTo-Json -Depth 5
Invoke-RestMethod http://localhost:8000/api/v1/retrieval/search `
-Method Post -ContentType application/json -Body $bodySSE 问答：
curl.exe -N -X POST http://localhost:8000/api/v1/chat/stream `
-H "Content-Type: application/json" `
-d "{\"knowledge_base_id\":\"$KB_ID\",\"query\":\"如何排查工具调用超时？\"}"运行评测：
uv run python scripts/run_eval.py --knowledge-base-id $KB_ID `
--dataset data/eval/orion_132.jsonl --mode hybrid完整接口可在 OpenAPI 页面调试。目录批量摄取使用 scripts/import_directory.py，
正式评测语料和题集使用 scripts/setup_benchmark.py 确定性生成。
快速 Smoke 评测先运行 scripts/setup_smoke.py，由新索引生成匹配的 Chunk ID。
132 条人工复核用例覆盖 13 篇 Orion 文档、78 个 Chunk，包括事实、错误码、版本与 模块 Filter、ACL、拒答、排障及跨文档查询。固定数据和参数结果如下：
| Mode | Recall@5 | MRR@10 | nDCG@10 | P50 ms | P95 ms |
|---|---|---|---|---|---|
| Dense | 0.9417 | 0.9340 | 0.9427 | 48.37 | 49.17 |
| Hybrid | 1.0000 | 0.9958 | 0.9896 | 48.48 | 52.84 |
| Hybrid + Rerank | 0.9833 | 0.8611 | 0.8880 | 104.55 | 314.71 |
当前语料推荐 Hybrid。Reranker 降低排序质量并增加延迟，因此保留为可替换实验阶段， 不宣称其带来提升。完整 Run ID、ACL/Filter 消融和复现说明见 evaluation.md。
uv run pytest -W error
uv run ruff check .
uv run alembic check
Set-Location frontend
npm run build
npm run test:e2e文档全生命周期可使用 scripts/verify_document_lifecycle.py 对运行中的 API 验证。
配置 LLM 后使用 scripts/verify_llm_workflow.py 验证引用生成、Trace 元数据和会话摘要。
演示步骤见 demo-script.md，简历描述见
resume.md。
最终自动化与真实 LLM 验收证据见 acceptance.md。
- PDF 支持文本型文档，不包含 OCR。
- 会话摘要和有证据回答依赖外部 LLM；未配置 Key 时返回
LLM_NOT_CONFIGURED。 - 当前 Cross-Encoder 不适合 Orion 评测语料，生产默认应选 Hybrid。
- 首次模型下载和 Reranker 冷启动会显著增加延迟。
- 开发身份回退只允许用于本地环境；生产部署需接入真实用户和组管理。