212 lines
4.1 KiB
Markdown
212 lines
4.1 KiB
Markdown
# 智能体总体设计文档
|
||
|
||
## 1. 设计目标
|
||
|
||
Agent 设计的核心目标是支持未知复试题的快速适配。
|
||
|
||
系统不针对单一业务写死，而是通过场景配置、知识库、工具和输出模板组合出不同业务 Agent。
|
||
|
||
```text
|
||
业务 Agent = 场景配置 + 知识库 + 工具集 + 输出模板 + 审计日志 + 模型适配器
|
||
```
|
||
|
||
## 2. Agent 类型
|
||
|
||
V1 预置 5 类 Agent 场景：
|
||
|
||
| Agent ID | 名称 | 适用场景 |
|
||
|---|---|---|
|
||
| `knowledge_qa` | 知识库问答助手 | SOP、制度、客服知识库 |
|
||
| `document_review` | 文档审核助手 | 合同、制度、SOP、材料审核 |
|
||
| `ticket_assistant` | 工单处理助手 | 客服、售后、运维工单 |
|
||
| `quality_analysis` | 质量异常分析助手 | 生产、质检、缺陷分析 |
|
||
| `risk_audit` | 风险审核助手 | 财务、采购、报销、合同风险 |
|
||
|
||
## 3. Agent 执行链路
|
||
|
||
```text
|
||
用户输入
|
||
↓
|
||
加载场景配置
|
||
↓
|
||
判断是否启用 RAG
|
||
↓
|
||
检索知识库片段
|
||
↓
|
||
加载可用工具
|
||
↓
|
||
构造 Prompt
|
||
↓
|
||
调用大模型
|
||
↓
|
||
解析工具调用和结构化输出
|
||
↓
|
||
生成 AgentResult
|
||
↓
|
||
写入审计日志
|
||
↓
|
||
页面展示
|
||
```
|
||
|
||
## 4. 场景配置结构
|
||
|
||
场景配置使用 YAML，V1 以配置文件作为场景唯一事实来源，后台管理不作为场景配置入口。
|
||
|
||
```yaml
|
||
id: quality_analysis
|
||
name: 质量异常分析助手
|
||
description: 用于分析生产质量异常、检索 SOP、生成处理建议
|
||
|
||
agent:
|
||
role: 质量管理专家
|
||
goal: 根据用户问题、知识库和工具结果，输出可执行的质量分析报告
|
||
system_prompt: ""
|
||
instructions:
|
||
- 回答必须基于知识库或工具结果
|
||
- 不确定时必须说明缺失信息
|
||
- 涉及质量风险时给出风险等级
|
||
|
||
rag:
|
||
enabled: true
|
||
collection: quality_docs
|
||
top_k: 5
|
||
|
||
tools:
|
||
- query_demo_records
|
||
- calculate_rate
|
||
|
||
output:
|
||
type: quality_report
|
||
|
||
audit:
|
||
enabled: true
|
||
log_retrieval: true
|
||
log_tool_calls: true
|
||
```
|
||
|
||
## 5. Prompt 组成
|
||
|
||
Prompt 建议由以下部分组成：
|
||
|
||
```text
|
||
系统角色
|
||
任务目标
|
||
行为约束
|
||
输出格式要求
|
||
知识库检索内容
|
||
工具调用结果
|
||
用户问题
|
||
```
|
||
|
||
V1 不追求复杂 Prompt 框架，优先保证可读、可改、可解释。
|
||
|
||
## 6. RAG 策略
|
||
|
||
RAG 在 V1 中负责给 Agent 提供题目材料和业务知识。
|
||
|
||
入库流程：
|
||
|
||
```text
|
||
上传文件
|
||
↓
|
||
抽取文本
|
||
↓
|
||
文本切分
|
||
↓
|
||
生成 embedding
|
||
↓
|
||
写入 Chroma
|
||
```
|
||
|
||
检索流程：
|
||
|
||
```text
|
||
用户问题
|
||
↓
|
||
按 scenario_id 和可选 document_ids 过滤
|
||
↓
|
||
向量检索 top_k
|
||
↓
|
||
返回片段内容、来源和分数
|
||
```
|
||
|
||
## 7. 工具调用策略
|
||
|
||
工具用于补足大模型不能直接可靠完成的业务动作。
|
||
|
||
V1 内置工具：
|
||
|
||
| 工具 | 用途 |
|
||
|---|---|
|
||
| `calculate_rate` | 计算比例、缺陷率、通过率 |
|
||
| `query_demo_records` | 查询模拟业务数据 |
|
||
| `check_required_fields` | 检查必填项 |
|
||
| `generate_action_items` | 生成行动项 |
|
||
|
||
工具返回格式：
|
||
|
||
```json
|
||
{
|
||
"tool_name": "calculate_rate",
|
||
"success": true,
|
||
"arguments": {},
|
||
"result": {},
|
||
"error": ""
|
||
}
|
||
```
|
||
|
||
## 8. 结构化输出
|
||
|
||
V1 支持以下输出类型：
|
||
|
||
- `general_answer`
|
||
- `document_review_report`
|
||
- `ticket_response`
|
||
- `quality_report`
|
||
- `risk_audit_report`
|
||
|
||
结构化输出优先使用 JSON。
|
||
|
||
解析失败时：
|
||
|
||
- 保留模型原始输出。
|
||
- 返回解析错误。
|
||
- 页面展示原始回答。
|
||
- 审计日志记录失败原因。
|
||
|
||
## 9. AgentResult
|
||
|
||
Agent Core 统一返回：
|
||
|
||
```json
|
||
{
|
||
"answer": "",
|
||
"structured_output": {},
|
||
"references": [],
|
||
"tool_calls": [],
|
||
"raw_output": "",
|
||
"model_name": "",
|
||
"latency_ms": 0,
|
||
"status": "success",
|
||
"error": ""
|
||
}
|
||
```
|
||
|
||
## 10. Adapter 策略
|
||
|
||
V1 默认使用自研轻量 Orchestrator，通过 OpenAI 兼容接口接入 LLM 与 Embedding，可自主选择 OpenAI、硅基流动等兼容服务。
|
||
|
||
后续可以扩展：
|
||
|
||
- OpenAI Agents SDK Adapter。
|
||
- Dify API Adapter。
|
||
- LangGraph Adapter。
|
||
|
||
所有 Adapter 应保持统一接口：
|
||
|
||
```text
|
||
run_agent(scenario_config, user_input, options=None) -> AgentResult
|
||
```
|
||
|
||
这样可以保证 Django 业务层不受底层 Agent 编排实现影响。
|