226 lines
5.1 KiB
Markdown
226 lines
5.1 KiB
Markdown
# 智能核心模块需求文档
|
||
|
||
## 1. 模块定位
|
||
|
||
Agent Core 是系统的智能能力核心，负责根据场景配置完成 RAG 检索、工具调用、大模型调用和结构化输出。
|
||
|
||
该模块应保持独立于 Django View，方便后续迁移为独立服务，或接入 OpenAI Agents SDK、Dify 等外部编排引擎。
|
||
|
||
## 2. 模块目标
|
||
|
||
- 提供统一 Agent 执行入口。
|
||
- 根据场景配置组织 Prompt。
|
||
- 支持 RAG 检索。
|
||
- 支持工具注册与调用。
|
||
- 支持 OpenAI API 兼容的 LLM 与 Embedding 调用，可自主接入 OpenAI、硅基流动等兼容服务。
|
||
- 支持结构化输出解析。
|
||
- 返回可审计的 AgentResult。
|
||
|
||
## 3. 职责边界
|
||
|
||
### 3.1 负责
|
||
|
||
- Agent 编排。
|
||
- 场景配置对象消费。
|
||
- RAG 入库和检索核心逻辑。
|
||
- 工具注册和工具执行。
|
||
- LLM Provider 适配。
|
||
- 输出结构化解析。
|
||
- 生成 AgentResult。
|
||
|
||
### 3.2 不负责
|
||
|
||
- 不渲染页面。
|
||
- 不直接处理 Django 表单。
|
||
- 不直接保存 Django Model。
|
||
- 不管理用户登录。
|
||
- 不负责 Docker 部署。
|
||
|
||
## 4. 子模块划分
|
||
|
||
```text
|
||
agent_core/
|
||
orchestrator.py
|
||
scenario_loader.py
|
||
llm_provider.py
|
||
tool_registry.py
|
||
structured_output.py
|
||
|
||
rag/
|
||
ingest.py
|
||
retriever.py
|
||
|
||
tools/
|
||
builtin_tools.py
|
||
|
||
schemas/
|
||
outputs.py
|
||
```
|
||
|
||
## 5. Orchestrator 需求
|
||
|
||
`orchestrator.py` 提供统一入口：
|
||
|
||
```text
|
||
run_agent(
|
||
scenario_config,
|
||
user_input,
|
||
options=None
|
||
) -> AgentResult
|
||
```
|
||
|
||
执行流程：
|
||
|
||
1. 读取场景配置。
|
||
2. 根据配置判断是否启用 RAG。
|
||
3. 按 `scenario_id` 和可选 `document_ids` 检索相关知识片段。
|
||
4. 根据配置加载可用工具。
|
||
5. 构造系统提示词。
|
||
6. 调用大模型。
|
||
7. 执行必要的工具调用。
|
||
8. 解析结构化输出。
|
||
9. 返回 AgentResult。
|
||
|
||
V1 可以使用轻量 Orchestrator，不强制引入完整 Agent SDK。
|
||
|
||
## 6. RAG 需求
|
||
|
||
### 6.1 入库
|
||
|
||
`rag/ingest.py` 负责：
|
||
|
||
- 接收文档文本。
|
||
- 文本切分。
|
||
- 通过 OpenAI 兼容 Embedding Provider 生成 embedding。
|
||
- 写入 Chroma。
|
||
- 保存 metadata。
|
||
|
||
metadata 至少包含：
|
||
|
||
- `scenario_id`
|
||
- `document_id`
|
||
- `source_file`
|
||
- `chunk_id`
|
||
- `created_at`
|
||
|
||
### 6.2 检索
|
||
|
||
`rag/retriever.py` 负责：
|
||
|
||
- 根据用户问题检索相关片段。
|
||
- 支持按 `scenario_id` 过滤。
|
||
- 支持按本次对话选择的 `document_ids` 过滤；未选择时使用当前场景全部已入库文档。
|
||
- 返回 top_k 结果。
|
||
- 返回内容、来源和分数。
|
||
|
||
## 7. 工具系统需求
|
||
|
||
`tool_registry.py` 负责工具注册、查找和执行。
|
||
|
||
V1 内置工具：
|
||
|
||
| 工具名 | 说明 |
|
||
|---|---|
|
||
| `calculate_rate` | 计算通过率、缺陷率、占比等 |
|
||
| `query_demo_records` | 查询模拟业务数据 |
|
||
| `check_required_fields` | 检查必填项是否缺失 |
|
||
| `generate_action_items` | 生成行动项清单 |
|
||
|
||
工具执行结果需要统一格式：
|
||
|
||
```json
|
||
{
|
||
"tool_name": "calculate_rate",
|
||
"success": true,
|
||
"arguments": {},
|
||
"result": {},
|
||
"error": ""
|
||
}
|
||
```
|
||
|
||
## 8. LLM Provider 需求
|
||
|
||
`llm_provider.py` 负责模型调用。
|
||
|
||
V1 需要支持 OpenAI API 兼容 LLM 接口：
|
||
|
||
- `LLM_API_KEY`
|
||
- `LLM_BASE_URL`
|
||
- `LLM_MODEL`
|
||
|
||
接口需要隐藏不同模型供应商差异，对 Orchestrator 暴露统一方法：
|
||
|
||
```text
|
||
generate(messages, response_format=None) -> LLMResponse
|
||
```
|
||
|
||
Embedding 也通过 OpenAI 兼容接口接入：
|
||
|
||
- `EMBEDDING_API_KEY`
|
||
- `EMBEDDING_BASE_URL`
|
||
- `EMBEDDING_MODEL`
|
||
|
||
当 Embedding 专用 Key 或 Base URL 为空时，可以复用 LLM 的 Key 和 Base URL。RAG 入库和检索必须通过真实 embedding 与 Chroma 完成，模拟 embedding 或简单文本匹配只能作为开发阶段临时桩，不计入 V1 验收。
|
||
|
||
## 9. 结构化输出需求
|
||
|
||
`structured_output.py` 负责将模型输出转换为业务结构。
|
||
|
||
V1 输出类型：
|
||
|
||
- `general_answer`
|
||
- `document_review_report`
|
||
- `ticket_response`
|
||
- `quality_report`
|
||
- `risk_audit_report`
|
||
|
||
解析策略：
|
||
|
||
- 优先要求模型直接返回 JSON。
|
||
- JSON 解析成功则展示结构化结果。
|
||
- JSON 解析失败则保留原始输出，并返回解析错误。
|
||
|
||
## 10. AgentResult 需求
|
||
|
||
Agent Core 最终返回统一结果对象。
|
||
|
||
字段：
|
||
|
||
| 字段 | 说明 |
|
||
|---|---|
|
||
| `answer` | 最终自然语言回答 |
|
||
| `structured_output` | 结构化输出 |
|
||
| `references` | RAG 引用片段 |
|
||
| `tool_calls` | 工具调用记录 |
|
||
| `raw_output` | 模型原始输出 |
|
||
| `model_name` | 模型名称 |
|
||
| `latency_ms` | 执行耗时 |
|
||
| `status` | `success` / `failed` |
|
||
| `error` | 错误信息 |
|
||
|
||
## 11. Adapter 扩展需求
|
||
|
||
V1 默认使用 `LightweightOrchestrator`。
|
||
|
||
后续可扩展：
|
||
|
||
- OpenAI Agents SDK Adapter。
|
||
- Dify API Adapter。
|
||
- LangGraph Adapter。
|
||
|
||
Adapter 需要保持同样输入输出：
|
||
|
||
```text
|
||
run_agent(scenario_config, user_input, options=None) -> AgentResult
|
||
```
|
||
|
||
## 12. 验收标准
|
||
|
||
- Chat 模块可以调用 Agent Core 获得统一 AgentResult。
|
||
- RAG 可以按场景检索知识片段。
|
||
- RAG 可以按本次对话选择的文档范围检索知识片段。
|
||
- 工具调用结果可以记录并返回。
|
||
- LLM 与 Embedding 配置可以通过环境变量切换。
|
||
- 结构化输出解析失败时不会导致整个流程崩溃。
|
||
- Agent Core 不依赖 Django View。
|