249 lines
7.0 KiB
Markdown
249 lines
7.0 KiB
Markdown
# Universal Agent Demo Framework
|
||
|
||
用于复试展示的通用 AI Agent Demo 框架。
|
||
|
||
项目目标不是提前猜中某一个具体业务题，而是先准备一个可快速改题的基础平台。拿到复试题目后，可以通过修改场景配置、上传知识库、补充少量工具函数，快速完成一个可演示的企业业务 Agent。
|
||
|
||
## 核心理念
|
||
|
||
```text
|
||
业务 Agent = 场景配置 + 知识库 + 工具集 + 输出模板 + 审计日志 + 模型适配器
|
||
```
|
||
|
||
## 技术路线
|
||
|
||
V1 采用：
|
||
|
||
- Django 单体应用
|
||
- 独立 Agent Core 模块
|
||
- SQLite
|
||
- Chroma
|
||
- Django Templates
|
||
- Docker Compose
|
||
- OpenAI API 兼容的 LLM 与 Embedding 接口
|
||
|
||
默认不强依赖 Dify。系统预留 Adapter 设计，后续可以接入 Dify、OpenAI Agents SDK 或其他 Agent 编排平台。
|
||
|
||
## 适用复试题型
|
||
|
||
| 题型 | 推荐场景模板 |
|
||
|---|---|
|
||
| SOP 问答 | `knowledge_qa` |
|
||
| 制度问答 | `knowledge_qa` |
|
||
| 文档审核 | `document_review` |
|
||
| 客服工单 | `ticket_assistant` |
|
||
| 质量异常分析 | `quality_analysis` |
|
||
| 财务审核 | `risk_audit` |
|
||
| 采购审核 | `risk_audit` |
|
||
| 合同风险分析 | `document_review` 或 `risk_audit` |
|
||
|
||
## 模块划分
|
||
|
||
```text
|
||
config
|
||
apps.scenarios
|
||
apps.documents
|
||
apps.chat
|
||
apps.audit
|
||
agent_core
|
||
```
|
||
|
||
职责边界：
|
||
|
||
- Django Apps 负责页面、数据、文件、日志等企业应用外壳。
|
||
- Agent Core 负责 RAG、工具调用、模型适配、结构化输出和 Agent 编排。
|
||
- RAG、工具调用和模型调用不直接写进 Django View。
|
||
|
||
## 推荐项目结构
|
||
|
||
```text
|
||
universal-agent-demo/
|
||
manage.py
|
||
requirements.txt
|
||
Dockerfile
|
||
docker-compose.yml
|
||
.env.example
|
||
README.md
|
||
AGENTS.md
|
||
|
||
config/
|
||
apps/
|
||
scenarios/
|
||
documents/
|
||
chat/
|
||
audit/
|
||
|
||
agent_core/
|
||
rag/
|
||
tools/
|
||
schemas/
|
||
|
||
configs/
|
||
knowledge_qa.yaml
|
||
document_review.yaml
|
||
ticket_assistant.yaml
|
||
quality_analysis.yaml
|
||
risk_audit.yaml
|
||
|
||
data/
|
||
uploads/
|
||
chroma/
|
||
|
||
docs/
|
||
```
|
||
|
||
## V1 功能范围
|
||
|
||
V1 需要完成：
|
||
|
||
- 场景列表。
|
||
- Agent 对话页。
|
||
- 文件上传。
|
||
- 文档入库。
|
||
- RAG 检索。
|
||
- 内置工具调用。
|
||
- 结构化输出展示。
|
||
- 审计日志。
|
||
- 模型 API 可配置。
|
||
- Docker 一键启动。
|
||
|
||
当前代码基线已经落地的能力：
|
||
|
||
- 首页支持展示场景摘要、适用题型、RAG 状态、工具数量。
|
||
- 非法 YAML 场景配置会被自动跳过，并在首页展示错误摘要。
|
||
- 对话页支持问题输入、文档范围选择、结构化结果、引用片段、工具调用和审计入口展示。
|
||
- 文档页支持上传、列表查看、手动入库、失败原因提示和重试。
|
||
- 审计页支持列表摘要、按场景筛选、详情查看、原始输出展示和敏感信息脱敏。
|
||
- Agent Core 已具备 Prompt 编排、OpenAI 兼容 Provider、结构化输出解析、RAG 检索和工具注册机制。
|
||
- 测试环境默认固定使用 Mock Provider，避免误调用本地真实模型配置。
|
||
|
||
V1 暂不重点做：
|
||
|
||
- 多租户。
|
||
- 复杂权限。
|
||
- 完整工作流引擎。
|
||
- 前后端分离。
|
||
- 深度 Dify 集成。
|
||
- 生产级高并发优化。
|
||
|
||
## 复试改题流程
|
||
|
||
拿到题目后：
|
||
|
||
1. 判断题目属于哪类模板。
|
||
2. 复制最接近的 YAML 场景配置。
|
||
3. 修改 Agent 角色、目标、指令和输出模板。
|
||
4. 上传题目材料。
|
||
5. 如需业务计算，新增一个工具函数。
|
||
6. 用 2 到 3 个问题测试效果。
|
||
7. 演示场景配置、知识库引用、工具调用、结构化输出和审计日志。
|
||
|
||
## 当前页面概览
|
||
|
||
当前项目包含以下主要页面：
|
||
|
||
| 页面 | 路径 | 当前能力 |
|
||
|---|---|---|
|
||
| 场景首页 | `/` | 展示场景名称、描述、适用题型、RAG 状态、工具数和配置异常摘要 |
|
||
| 对话页 | `/chat/<scenario_id>/` | 输入问题、勾选已入库文档、查看结构化结果、引用片段、工具调用和审计入口 |
|
||
| 文档列表页 | `/documents/` | 查看文档状态、错误信息、上传时间并手动触发入库 |
|
||
| 文档上传页 | `/documents/upload/` | 选择场景并上传 `.txt`、`.md`、`.pdf`、`.docx` 文件 |
|
||
| 审计列表页 | `/audit/` | 查看执行摘要并按场景筛选 |
|
||
| 审计详情页 | `/audit/<log_id>/` | 查看输入、最终回答、结构化输出、引用、工具调用、原始输出和错误信息 |
|
||
|
||
## 计划启动方式
|
||
|
||
本地启动：
|
||
|
||
```bash
|
||
pip install -r requirements.txt
|
||
python manage.py migrate
|
||
python manage.py runserver
|
||
```
|
||
|
||
Docker 启动：
|
||
|
||
```bash
|
||
docker compose up --build
|
||
```
|
||
|
||
当前文档目标已统一为完整 V1 闭环：真实 Chroma RAG、OpenAI 兼容 LLM、OpenAI 兼容 Embedding、工具注册和审计日志。开发阶段可以用测试桩验证页面和边界，但不作为 V1 验收结果。
|
||
|
||
推荐首次启动步骤：
|
||
|
||
```bash
|
||
python -m venv .venv
|
||
.venv\Scripts\activate
|
||
pip install -r requirements.txt
|
||
python manage.py migrate
|
||
python manage.py runserver
|
||
```
|
||
|
||
## 环境变量
|
||
|
||
项目当前通过 `os.environ` 读取配置，核心变量如下：
|
||
|
||
```env
|
||
DJANGO_SECRET_KEY=replace-with-a-local-secret-key
|
||
DJANGO_DEBUG=true
|
||
DJANGO_ALLOWED_HOSTS=*
|
||
|
||
LLM_API_KEY=your_llm_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` 只作为模板，不应填写真实密钥并提交到仓库。
|
||
- 当前代码会在 Django settings 初始化时自动加载根目录 `.env`，本地 `python manage.py runserver`、`pytest` 和 Docker Compose 可以复用同一套配置。
|
||
- Docker Compose 当前在 `docker-compose.yml` 中通过 `env_file` 读取 `.env`。
|
||
|
||
常见做法：
|
||
|
||
- 本地开发：复制 `.env.example` 为 `.env`，填入真实参数后运行。
|
||
- Docker 演示：确认 `.env` 已配置后，再执行 `docker compose up --build`。
|
||
|
||
## 测试与验证
|
||
|
||
当前项目已经补有较完整的模块级测试，覆盖：
|
||
|
||
- 场景配置读取、非法配置容错和首页展示。
|
||
- 对话提交、文档范围传递、结构化结果展示。
|
||
- 文档上传、文本抽取、入库成功与失败提示。
|
||
- 审计日志落库、筛选、原始输出展示和 API Key 脱敏。
|
||
- Agent Core 的 Prompt 编排、结构化解析、RAG fallback 检索。
|
||
- Tool Registry 和内置工具行为。
|
||
- LLM / Embedding Provider 的配置与请求构造。
|
||
|
||
常用验证命令：
|
||
|
||
```bash
|
||
pytest
|
||
python manage.py check
|
||
docker compose config
|
||
```
|
||
|
||
说明：
|
||
|
||
- 测试环境默认通过 `tests/conftest.py` 固定 `LLM_PROVIDER=mock`，避免回归测试误走真实网络请求。
|
||
- 当前本地 `.env` 可能包含真实模型配置，但不会影响自动化测试稳定性。
|
||
|
||
## 文档入口
|
||
|
||
- [V1 总需求文档](docs/需求分析/1.V1总需求文档.md)
|
||
- [模块需求文档索引](docs/需求分析/2.模块需求索引.md)
|
||
- [智能体总体设计](docs/设计文档/1.智能体总体设计.md)
|
||
- [设计文档索引](docs/设计文档/0.设计文档索引.md)
|
||
- [协作与编码约定](AGENTS.md)
|