|
|
@@ -0,0 +1,168 @@
|
|
|
+# qaagent67 — 文档问答智能体 ❓
|
|
|
+
|
|
|
+不断加入文件，然后针对内容提问。回答带引用来源，经过事实核查。
|
|
|
+
|
|
|
+## 快速使用
|
|
|
+
|
|
|
+```bash
|
|
|
+# 启动问答智能体
|
|
|
+lambdagent run agentexample/qaagent67/agent-config.yml "加入 docs/ 目录下的所有文件"
|
|
|
+```
|
|
|
+
|
|
|
+## 对话示例
|
|
|
+
|
|
|
+```
|
|
|
+用户: 加入 /path/to/docs 目录下的所有文件
|
|
|
+
|
|
|
+qaagent: ✅ 索引完成
|
|
|
+ 文件数: 12
|
|
|
+ 总块数: 184
|
|
|
+ 知识库: qaagent_default
|
|
|
+
|
|
|
+ 文件清单:
|
|
|
+ paper.pdf (pdf) → 28 个块
|
|
|
+ api.py (py) → 15 个块
|
|
|
+ config.md (md) → 8 个块
|
|
|
+ ...
|
|
|
+
|
|
|
+用户: 这些文件里提到了哪些性能优化建议？
|
|
|
+
|
|
|
+qaagent: 根据文档，有以下性能优化建议:
|
|
|
+
|
|
|
+ 1. 使用数据库连接池 (pool_size=20) 减少连接开销
|
|
|
+ [来源: config.md §3, perf.py L42]
|
|
|
+
|
|
|
+ 2. 对热点查询使用 Redis 缓存
|
|
|
+ [来源: architecture.md §4.2]
|
|
|
+
|
|
|
+ 3. API 响应使用 lru_cache 装饰器
|
|
|
+ [来源: api.py L120]
|
|
|
+
|
|
|
+ ✓ 以上所有建议均已通过原文验证。
|
|
|
+
|
|
|
+用户: 知识库里现在有哪些文件？
|
|
|
+
|
|
|
+qaagent: 📋 知识库状态 (qaagent_default):
|
|
|
+ 总文件: 12 个
|
|
|
+ 总块数: 184 个
|
|
|
+ ...
|
|
|
+
|
|
|
+用户: 对比 api.py 和 auth.py 的鉴权方式有什么差异？
|
|
|
+
|
|
|
+qaagent: (判断: 这是对比分析 → 调用 DeepAnalysis)
|
|
|
+
|
|
|
+🔬 深度分析 — 3 路并行检索完成
|
|
|
+
|
|
|
+ 1. api.py 的鉴权实现:
|
|
|
+ 使用 JWT Bearer Token，在中间件层验证 [来源: api.py L15-30]
|
|
|
+
|
|
|
+ 2. auth.py 的鉴权实现:
|
|
|
+ 使用 OAuth2 + PKCE 流程，支持第三方登录 [来源: auth.py L42-80]
|
|
|
+
|
|
|
+ 3. 共同点:
|
|
|
+ 都使用 HTTPS + CORS 白名单 [来源: config.md §security]
|
|
|
+
|
|
|
+ **结论**: api.py 适合内部微服务通信 (JWT 无状态),
|
|
|
+ auth.py 适合面向用户的前端应用 (OAuth2 标准流程)。
|
|
|
+```
|
|
|
+
|
|
|
+## 架构: 混合模式 (工具 + SubAgent)
|
|
|
+
|
|
|
+```
|
|
|
+简单操作 → ReAct + 工具 (快, 零 LLM 成本)
|
|
|
+复杂推理 → SubAgent 并行编排 (深, 多路检索+综合)
|
|
|
+
|
|
|
+判断标准: 主 Agent 根据问题类型自动选择
|
|
|
+
|
|
|
+三层架构:
|
|
|
+ Layer 1 — Skill (7 个)
|
|
|
+ file-reader, chunk-splitter, knowledge-indexer ← 纯工具，无 LLM
|
|
|
+ context-retriever ← 纯工具，向量搜索
|
|
|
+ answer-generator, source-citer, fact-checker ← 需要 LLM
|
|
|
+
|
|
|
+ Layer 2 — Pattern (2 个)
|
|
|
+ 喂文件: map_reduce (分而治之模式)
|
|
|
+ 提问: pipeline + review (流水线 + 审查模式)
|
|
|
+
|
|
|
+ Layer 3 — Orchestration
|
|
|
+ agent-config.yml (ReAct 主循环，选择调用哪个工具)
|
|
|
+```
|
|
|
+
|
|
|
+## 工具
|
|
|
+
|
|
|
+| 工具 | 功能 | 模式 | LLM? |
|
|
|
+|------|------|------|------|
|
|
|
+| `IngestFiles` | 批量喂文件 (文件/目录/glob) | map_reduce (工具) | 否 |
|
|
|
+| `QueryKnowledge` | 简单事实查询 | pipeline (工具) | 否 (检索) |
|
|
|
+| `DeepAnalysis` | 复杂对比/总结/评估 | fan_out_merge (SubAgent) | 是 (并行) |
|
|
|
+| `ListKnowledge` | 查看已索引文件 | 直接 (工具) | 否 |
|
|
|
+| `RemoveKnowledge` | 删除文件索引 | 直接 (工具) | 否 |
|
|
|
+
|
|
|
+### 何时用 QueryKnowledge vs DeepAnalysis
|
|
|
+
|
|
|
+```
|
|
|
+QueryKnowledge (快):
|
|
|
+ "API 端口是多少？" → 精确查找
|
|
|
+ "用了什么数据库？" → 事实检索
|
|
|
+
|
|
|
+DeepAnalysis (深):
|
|
|
+ "对比 A 和 B 的差异" → 多路并行检索 + 对比分析
|
|
|
+ "从安全和性能角度评估" → 多维度并行 + 综合
|
|
|
+ "总结所有文件核心观点" → 逐文件检索 + 合并
|
|
|
+```
|
|
|
+
|
|
|
+## 支持的文件格式
|
|
|
+
|
|
|
+txt, md, py, js, ts, java, go, rs, c, cpp, css, html, xml, json, yaml, yml,
|
|
|
+toml, ini, sh, sql, rb, php, swift, kt, pdf, csv, log
|
|
|
+
|
|
|
+## 配置
|
|
|
+
|
|
|
+```yaml
|
|
|
+# 关键配置项
|
|
|
+model:
|
|
|
+ provider: ollama # 或 dashscope
|
|
|
+ name: qwen2.5:32b
|
|
|
+ baseUrl: http://localhost:11434
|
|
|
+
|
|
|
+rag:
|
|
|
+ collection: maritime_rag # 知识库名称
|
|
|
+ chunkSize: 512 # 分块大小 (token)
|
|
|
+ topK: 5 # 检索返回数量
|
|
|
+
|
|
|
+runtime:
|
|
|
+ engine: cek # CEK 引擎: 成本监控 + 循环检测
|
|
|
+ costBudget: 0.50 # 最大成本 $0.50
|
|
|
+```
|
|
|
+
|
|
|
+### 路径配置（可部署适配）
|
|
|
+
|
|
|
+所有文件路径集中在 `agent-config.yml` 的 `knowledge` 字段，部署时只需修改这里：
|
|
|
+
|
|
|
+```yaml
|
|
|
+knowledge:
|
|
|
+ baseDir: /data/knowledge/maritime # 知识库根目录
|
|
|
+ rawDir: /data/knowledge/maritime/raw # 原始 PDF/文档
|
|
|
+ processedDir: /data/knowledge/maritime/processed # 提取后的文本
|
|
|
+ indexFile: /data/knowledge/maritime/rag_index.json
|
|
|
+ keywordFile: /data/knowledge/maritime/rag_index.keywords.json
|
|
|
+```
|
|
|
+
|
|
|
+Python 代码通过读取 YAML 获取路径，不硬编码：
|
|
|
+
|
|
|
+```python
|
|
|
+# search_engine.py / app.py 都从配置读取
|
|
|
+config_path = os.environ.get("AGENT_CONFIG", "agent-config.yml")
|
|
|
+with open(config_path) as f:
|
|
|
+ config = yaml.safe_load(f)
|
|
|
+knowledge_dir = config["knowledge"]["baseDir"]
|
|
|
+```
|
|
|
+
|
|
|
+环境变量 fallback：`AGENT_CONFIG` 指定配置文件路径，`KNOWLEDGE_DIR` 指定知识库目录。
|
|
|
+
|
|
|
+## Skill 定义
|
|
|
+
|
|
|
+位于 `skills/` 目录:
|
|
|
+- `answer-generator.yml` — 回答生成器 (LLM)
|
|
|
+- `source-citer.yml` — 来源标注器 (LLM)
|
|
|
+- `fact-checker.yml` — 事实核查器 (LLM, 审查模式审查者)
|
kenny67nju