584 lines
14 KiB
Markdown
584 lines
14 KiB
Markdown
# Universal Agent Demo Framework V1 需求文档
|
||
|
||
## 1. 项目背景
|
||
|
||
本项目用于复试展示。复试题目暂时未知，但大概率围绕企业生产、质量、客服、财务、SOP、文档审核、工单处理等场景。
|
||
|
||
项目目标不是提前猜中某一个具体业务题，而是先搭建一个通用 AI Agent Demo 底座。拿到复试题目后，可以通过修改场景配置、上传知识库、补充少量业务工具，快速生成一个可演示的业务 Agent 系统。
|
||
|
||
核心理念：
|
||
|
||
```text
|
||
业务 Agent = 场景配置 + 知识库 + 工具集 + 输出模板 + 审计日志 + 模型适配器
|
||
```
|
||
|
||
## 2. 项目目标
|
||
|
||
V1 版本目标是实现一个可运行、可演示、可快速改题的基础平台。
|
||
|
||
系统需要支持：
|
||
|
||
- 通过配置快速创建不同业务 Agent。
|
||
- 支持上传文档并构建 RAG 知识库。
|
||
- 支持根据场景调用内置业务工具。
|
||
- 支持结构化输出，方便展示报告、风险点、建议动作等结果。
|
||
- 支持审计日志，记录用户输入、检索内容、工具调用和模型输出。
|
||
- 支持 Docker 一键启动，降低复试现场环境风险。
|
||
- 支持快速替换大模型 API。
|
||
|
||
## 3. 非目标
|
||
|
||
V1 不追求完整企业级平台能力，以下内容暂不作为第一版重点：
|
||
|
||
- 复杂权限系统。
|
||
- 多租户管理。
|
||
- 完整工作流引擎。
|
||
- 复杂多 Agent 协作。
|
||
- 前后端分离架构。
|
||
- 深度集成 Dify。
|
||
- 生产级高并发优化。
|
||
- 完整在线文档协同编辑。
|
||
|
||
## 4. 技术方案
|
||
|
||
### 4.1 总体架构
|
||
|
||
V1 使用 Django 单体应用承载企业系统外壳，Agent Core 作为独立 Python 模块承载智能编排能力。
|
||
|
||
```text
|
||
Django Monolith
|
||
|
|
||
|-- Web UI
|
||
| |-- 场景选择
|
||
| |-- Agent 对话
|
||
| |-- 文件上传
|
||
| |-- 结构化结果展示
|
||
| |-- 审计日志查看
|
||
|
|
||
|-- Django Admin
|
||
| |-- 上传文件管理
|
||
| |-- 审计日志管理
|
||
| |-- 示例业务数据管理
|
||
|
|
||
|-- Agent Core
|
||
| |-- 场景配置加载
|
||
| |-- RAG 检索
|
||
| |-- 工具注册与调用
|
||
| |-- 大模型适配
|
||
| |-- 结构化输出解析
|
||
|
|
||
|-- Storage
|
||
|-- SQLite
|
||
|-- Chroma
|
||
|-- Uploaded Files
|
||
```
|
||
|
||
### 4.2 技术栈
|
||
|
||
| 模块 | 技术 | 说明 |
|
||
|---|---|---|
|
||
| Web 框架 | Django | 负责页面、模型、后台、文件上传和业务管理 |
|
||
| 页面渲染 | Django Templates + Bootstrap | 降低前端复杂度，快速完成 Demo |
|
||
| 数据库 | SQLite | V1 默认数据库，适合本地演示 |
|
||
| 向量库 | Chroma | 本地 RAG 知识库 |
|
||
| Agent Core | 自研轻量 Orchestrator | 保证可控、易讲解、易改题 |
|
||
| LLM 接入 | OpenAI API 兼容接口 | 方便切换 OpenAI、硅基流动等兼容服务、国产模型或本地代理 |
|
||
| Embedding 接入 | OpenAI API 兼容接口 | 用于文档向量化，供应商可自主选择 |
|
||
| 部署 | Docker + Docker Compose | 支持一键启动 |
|
||
|
||
## 5. 用户角色
|
||
|
||
V1 只设计一个主要用户角色：
|
||
|
||
### Demo 操作者
|
||
|
||
通常是复试时的展示者，负责选择场景、上传材料、输入问题、查看 Agent 输出和审计记录。
|
||
|
||
暂不区分管理员、业务人员、审核人员等复杂角色。
|
||
|
||
## 6. 核心使用流程
|
||
|
||
### 6.1 复试前准备流程
|
||
|
||
1. 启动系统。
|
||
2. 选择或复制一个已有场景模板。
|
||
3. 根据题目修改场景配置。
|
||
4. 上传题目相关文档。
|
||
5. 如有必要，补充一个业务工具函数。
|
||
6. 运行一次测试对话。
|
||
7. 使用审计日志确认 RAG、工具调用和输出链路正常。
|
||
|
||
### 6.2 复试演示流程
|
||
|
||
1. 打开系统首页。
|
||
2. 展示系统支持多个业务场景。
|
||
3. 选择当前题目对应的 Agent。
|
||
4. 上传或选择知识库文档。
|
||
5. 输入业务问题。
|
||
6. 展示 Agent 的结构化输出。
|
||
7. 展示引用来源、工具调用和审计日志。
|
||
8. 说明同一平台可通过配置切换到其他业务场景。
|
||
|
||
## 7. 场景模板
|
||
|
||
V1 预置 5 类通用场景模板，用于覆盖大多数复试题型。
|
||
|
||
| 模板 ID | 模板名称 | 适用题型 |
|
||
|---|---|---|
|
||
| knowledge_qa | 知识库问答助手 | SOP、制度、客服知识库、内部文档问答 |
|
||
| document_review | 文档审核助手 | 合同审核、制度审核、SOP 审核、材料合规检查 |
|
||
| ticket_assistant | 工单处理助手 | 客服工单、售后工单、运维工单 |
|
||
| quality_analysis | 质量异常分析助手 | 生产质量、缺陷分析、原因定位 |
|
||
| risk_audit | 风险审核助手 | 财务审核、采购审核、报销审核、合同风险 |
|
||
|
||
## 8. 场景配置需求
|
||
|
||
场景应通过 YAML 或 JSON 文件定义，避免把业务逻辑写死在代码中。
|
||
|
||
配置内容包括：
|
||
|
||
- 场景 ID。
|
||
- 场景名称。
|
||
- 场景描述。
|
||
- Agent 角色。
|
||
- Agent 任务目标。
|
||
- 系统提示词 可选。
|
||
- 是否启用 RAG。
|
||
- RAG 检索参数。
|
||
- 可用工具列表。
|
||
- 输出模板类型。
|
||
- 审计策略。
|
||
|
||
示例：
|
||
|
||
```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
|
||
```
|
||
|
||
## 9. 功能需求
|
||
|
||
### 9.1 首页
|
||
|
||
首页需要展示系统定位和可用场景列表。
|
||
|
||
页面能力：
|
||
|
||
- 查看所有 Agent 场景。
|
||
- 进入某个场景的对话页。
|
||
- 查看最近审计日志入口。
|
||
- 查看文件上传入口。
|
||
|
||
### 9.2 场景选择
|
||
|
||
系统需要支持从预置模板中选择业务场景。
|
||
|
||
V1 从 YAML 配置文件读取场景。后台管理只负责上传文件、审计日志和示例业务数据管理，不作为场景配置入口。
|
||
|
||
最低要求：
|
||
|
||
- 展示场景名称。
|
||
- 展示场景描述。
|
||
- 展示场景适用题型。
|
||
- 点击后进入对应 Agent 对话页。
|
||
|
||
### 9.3 Agent 对话
|
||
|
||
Agent 对话页是核心演示页面。
|
||
|
||
页面需要包含：
|
||
|
||
- 当前场景名称。
|
||
- 用户输入框。
|
||
- 文件上下文选择，可多选当前场景已入库文档；不选时默认使用当前场景全部已入库文档。
|
||
- Agent 输出区域。
|
||
- 结构化结果展示区域。
|
||
- 引用片段展示区域。
|
||
- 工具调用展示区域。
|
||
|
||
Agent 执行流程：
|
||
|
||
1. 接收用户问题。
|
||
2. 加载当前场景配置。
|
||
3. 如果启用 RAG，则检索相关知识片段。
|
||
4. 根据场景判断是否调用工具。
|
||
5. 调用大模型生成结果。
|
||
6. 解析为结构化输出。
|
||
7. 写入审计日志。
|
||
8. 返回页面展示。
|
||
|
||
### 9.4 文件上传
|
||
|
||
系统需要支持上传题目材料和知识库文档。
|
||
|
||
V1 支持的文件类型：
|
||
|
||
- TXT
|
||
- Markdown
|
||
- PDF
|
||
- DOCX
|
||
- XLSX 可作为后续增强
|
||
|
||
文件上传后需要保存：
|
||
|
||
- 原始文件名。
|
||
- 文件路径。
|
||
- 文件类型。
|
||
- 上传时间。
|
||
- 关联场景。
|
||
- 是否已入库。
|
||
|
||
### 9.5 RAG 知识库
|
||
|
||
系统需要支持将上传文档写入向量库，并在 Agent 对话时检索。
|
||
|
||
V1 RAG 流程：
|
||
|
||
1. 读取上传文件文本。
|
||
2. 按固定长度切分文本。
|
||
3. 生成 embedding。
|
||
4. 写入 Chroma collection。
|
||
5. 对话时根据用户问题检索 top_k 片段。
|
||
6. 将片段作为上下文传给 Agent。
|
||
7. 在结果中展示引用来源。
|
||
|
||
### 9.6 工具调用
|
||
|
||
系统需要提供一个工具注册机制。
|
||
|
||
V1 内置工具建议包括：
|
||
|
||
| 工具名 | 用途 |
|
||
|---|---|
|
||
| calculate_rate | 计算比例、缺陷率、通过率等指标 |
|
||
| query_demo_records | 查询模拟业务数据 |
|
||
| check_required_fields | 检查文档或表单必填项 |
|
||
| generate_action_items | 根据问题生成行动项 |
|
||
|
||
工具调用需要记录到审计日志中。
|
||
|
||
### 9.7 结构化输出
|
||
|
||
不同场景需要不同输出模板。
|
||
|
||
V1 至少支持以下输出类型：
|
||
|
||
#### 通用问答输出
|
||
|
||
- answer
|
||
- references
|
||
- confidence
|
||
|
||
#### 文档审核输出
|
||
|
||
- summary
|
||
- issues
|
||
- risk_level
|
||
- suggestions
|
||
- missing_items
|
||
- references
|
||
|
||
#### 工单处理输出
|
||
|
||
- reply
|
||
- category
|
||
- priority
|
||
- suggested_action
|
||
- need_human_review
|
||
|
||
#### 质量分析输出
|
||
|
||
- summary
|
||
- possible_causes
|
||
- evidence
|
||
- risk_level
|
||
- suggested_actions
|
||
- references
|
||
|
||
### 9.8 审计日志
|
||
|
||
系统需要记录每次 Agent 执行过程。
|
||
|
||
审计字段：
|
||
|
||
- 日志 ID。
|
||
- 场景 ID。
|
||
- 用户输入。
|
||
- 检索片段。
|
||
- 工具调用记录。
|
||
- 模型名称。
|
||
- 结构化输出。
|
||
- 原始输出。
|
||
- 执行耗时。
|
||
- 创建时间。
|
||
|
||
审计日志页面需要支持：
|
||
|
||
- 查看日志列表。
|
||
- 查看单条日志详情。
|
||
- 展示检索内容。
|
||
- 展示工具调用。
|
||
- 展示最终输出。
|
||
|
||
### 9.9 模型适配
|
||
|
||
系统需要通过统一接口调用大模型，避免模型 API 写死。
|
||
|
||
V1 模型适配器需要支持：
|
||
|
||
- 从环境变量读取 API Key。
|
||
- 从环境变量读取 Base URL。
|
||
- 从环境变量读取 Model Name。
|
||
- 支持 OpenAI API 兼容格式，可接入 OpenAI、硅基流动等兼容供应商。
|
||
- 支持独立配置 Embedding 模型，用于 RAG 入库和检索。
|
||
|
||
环境变量示例：
|
||
|
||
```env
|
||
DJANGO_SECRET_KEY=replace-with-a-local-secret-key
|
||
DJANGO_DEBUG=true
|
||
DJANGO_ALLOWED_HOSTS=*
|
||
|
||
LLM_API_KEY=your_api_key
|
||
LLM_BASE_URL=https://api.openai.com/v1
|
||
LLM_MODEL=gpt-4.1-mini
|
||
EMBEDDING_API_KEY=
|
||
EMBEDDING_BASE_URL=
|
||
EMBEDDING_MODEL=text-embedding-3-small
|
||
SCENARIO_CONFIG_DIR=configs
|
||
UPLOAD_ROOT=data/uploads
|
||
CHROMA_PATH=data/chroma
|
||
```
|
||
|
||
补充说明：
|
||
|
||
- `EMBEDDING_API_KEY` 为空时可复用 `LLM_API_KEY`。
|
||
- `EMBEDDING_BASE_URL` 为空时可复用 `LLM_BASE_URL`。
|
||
- `.env.example` 仅作为模板，不允许放真实密钥。
|
||
- 当前 V1 代码会在 settings 初始化时自动读取根目录 `.env`，本地运行与 `pytest` 可复用同一套配置；当前 Docker Compose 配置也通过 `env_file` 读取 `.env`。
|
||
|
||
## 10. Dify 集成策略
|
||
|
||
V1 不把 Dify 作为核心依赖。
|
||
|
||
原因：
|
||
|
||
- 复试现场需要最大程度保证可控。
|
||
- 自研 Agent Core 更方便解释架构设计。
|
||
- 题目未知时，直接依赖外部平台会增加部署和调试风险。
|
||
- Django + Agent Core 已能覆盖第一版演示需求。
|
||
|
||
系统预留 Agent Engine Adapter 概念，后续可接入 Dify、OpenAI Agents SDK 或其他企业 AI 平台。
|
||
|
||
V1 默认引擎：
|
||
|
||
```text
|
||
Lightweight Orchestrator
|
||
```
|
||
|
||
后续可扩展：
|
||
|
||
```text
|
||
Dify API Adapter
|
||
OpenAI Agents SDK Adapter
|
||
LangGraph Adapter
|
||
```
|
||
|
||
## 11. Docker 部署需求
|
||
|
||
系统需要支持 Docker Compose 一键启动。
|
||
|
||
基础命令：
|
||
|
||
```bash
|
||
docker compose up --build
|
||
```
|
||
|
||
V1 容器内容：
|
||
|
||
- Django Web 服务。
|
||
- SQLite 数据文件挂载。
|
||
- Chroma 数据目录挂载。
|
||
- 上传文件目录挂载。
|
||
|
||
V1 暂不强制引入 PostgreSQL。如果后续需要更正式的部署效果，可以在 Docker Compose 中增加 PostgreSQL 服务。
|
||
|
||
## 12. 推荐项目结构
|
||
|
||
```text
|
||
universal-agent-demo/
|
||
manage.py
|
||
requirements.txt
|
||
Dockerfile
|
||
docker-compose.yml
|
||
.env.example
|
||
README.md
|
||
|
||
config/
|
||
settings.py
|
||
urls.py
|
||
wsgi.py
|
||
asgi.py
|
||
|
||
apps/
|
||
scenarios/
|
||
models.py
|
||
admin.py
|
||
services.py
|
||
|
||
chat/
|
||
views.py
|
||
urls.py
|
||
forms.py
|
||
|
||
documents/
|
||
models.py
|
||
views.py
|
||
services.py
|
||
|
||
audit/
|
||
models.py
|
||
admin.py
|
||
services.py
|
||
|
||
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
|
||
|
||
configs/
|
||
knowledge_qa.yaml
|
||
document_review.yaml
|
||
ticket_assistant.yaml
|
||
quality_analysis.yaml
|
||
risk_audit.yaml
|
||
|
||
data/
|
||
uploads/
|
||
chroma/
|
||
db.sqlite3
|
||
|
||
templates/
|
||
base.html
|
||
home.html
|
||
chat/index.html
|
||
documents/upload.html
|
||
audit/logs.html
|
||
|
||
static/
|
||
css/
|
||
js/
|
||
```
|
||
|
||
## 13. 模块需求文档
|
||
|
||
V1 按 6 个核心模块拆分，具体模块需求见：
|
||
|
||
| 模块 | 文档 |
|
||
|---|---|
|
||
| 配置 | `docs/需求分析/3.配置模块需求.md` |
|
||
| 场景 | `docs/需求分析/4.场景模块需求.md` |
|
||
| 文档 | `docs/需求分析/5.文档模块需求.md` |
|
||
| 对话 | `docs/需求分析/6.对话模块需求.md` |
|
||
| 审计 | `docs/需求分析/7.审计模块需求.md` |
|
||
| 智能核心 | `docs/需求分析/8.智能核心模块需求.md` |
|
||
|
||
模块总览见：
|
||
|
||
```text
|
||
docs/需求分析/2.模块需求索引.md
|
||
```
|
||
|
||
## 14. V1 验收标准
|
||
|
||
V1 完成后，需要满足以下验收标准：
|
||
|
||
- 可以通过 Docker Compose 启动系统。
|
||
- 首页可以看到至少 5 个预置场景。
|
||
- 可以进入某个场景进行 Agent 对话。
|
||
- 可以上传 TXT、Markdown、PDF 或 DOCX 文件。
|
||
- 可以将上传文件写入本地知识库。
|
||
- Agent 回答时可以使用知识库检索结果。
|
||
- 至少支持 2 个内置工具调用。
|
||
- Agent 输出可以以结构化方式展示。
|
||
- 每次对话都会生成审计日志。
|
||
- 审计日志中可以查看用户问题、检索内容、工具调用和最终输出。
|
||
- 可以通过环境变量切换大模型 API 地址和模型名。
|
||
|
||
## 15. 复试改题策略
|
||
|
||
拿到题目后，优先按以下步骤适配：
|
||
|
||
1. 判断题目属于哪类模板。
|
||
2. 复制最接近的 YAML 场景配置。
|
||
3. 修改 Agent 角色、任务目标和输出模板。
|
||
4. 上传题目给出的文档或样例数据。
|
||
5. 如果题目需要业务计算，则新增一个工具函数。
|
||
6. 用 2 到 3 个测试问题验证效果。
|
||
7. 演示时重点展示配置、知识库、工具调用、结构化输出和审计日志。
|
||
|
||
题型映射：
|
||
|
||
| 题目类型 | 优先模板 |
|
||
|---|---|
|
||
| SOP 问答 | knowledge_qa |
|
||
| 制度问答 | knowledge_qa |
|
||
| 文档审核 | document_review |
|
||
| 客服处理 | ticket_assistant |
|
||
| 质量异常分析 | quality_analysis |
|
||
| 财务审核 | risk_audit |
|
||
| 采购审核 | risk_audit |
|
||
| 合同风险分析 | document_review 或 risk_audit |
|
||
|
||
## 16. 后续迭代方向
|
||
|
||
V1 完成后，可以根据时间增加以下能力：
|
||
|
||
- 支持 Excel 数据分析工具。
|
||
- 支持后台页面编辑场景配置，并同步生成或更新 YAML。
|
||
- 支持流式输出。
|
||
- 支持 OpenAI Agents SDK Adapter。
|
||
- 支持 Dify API Adapter。
|
||
- 支持 PostgreSQL 部署模式。
|
||
- 支持简单登录认证。
|
||
- 支持演示数据一键初始化。
|