lq/xk-ai-agent
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
main
xk-ai-agent/README.md

283 lines
10 KiB
Markdown
Raw Permalink Normal View History

初始化
2026-08-14 21:50:48 +08:00
# 中医 AI Agent 系统 v2.0
基于 **Go + MaxKB + 多模型工厂** 的专业领域 AI Agent 脚手架。
## 🆕 v2.0 核心升级：模型工厂模式
**一个系统，多种模型，按场景自动路由，主挂了自动降级。**
```
┌─────────────────────────────────────────────────────────────┐
│ HTTP API Layer (Gin) │
│ /api/v1/emr /api/v1/prescription /api/v1/agent │
├─────────────────────────────────────────────────────────────┤
│ Handler Layer (业务编排) │
│ 参数校验 → 调用Agent → 持久化 → 响应封装 │
├─────────────────────────────────────────────────────────────┤
│ Agent Engine (核心引擎) │
│ ┌────────────────────────────────────────────────────────┐ │
│ │ Runner → Planner → LLM → Tool Call → Reflect → Out │ │
│ └────────────────────────────────────────────────────────┘ │
├──────────────┬──────────────┬───────────────────────────────┤
│ Tool Set │ Rule Engine │ Memory & Session │
│ ├ MaxKB检索 │ 十八反十九畏 │ 短期：Session History │
│ ├ HIS查询 │ 剂量校验 │ 长期：向量数据库 │
│ ├ 药典查询 │ 孕妇禁忌 │ │
│ └ 规则校验 │ 术语规范 │ │
├──────────────┴──────────────┴───────────────────────────────┤
│ LLM 模型工厂（v2.0 核心） │
│ ┌───────────────────────────────────────────────────────┐ │
│ │ Factory → Router → FallbackChain │ │
│ │ ├ deepseek (病历生成主力) │ │
│ │ ├ openai/gpt-4o (处方校验) │ │
│ │ ├ qwen-max (中文知识问答) │ │
│ │ ├ azure (企业合规部署) │ │
│ │ └ ollama (本地离线兜底) │ │
│ └───────────────────────────────────────────────────────┘ │
├─────────────────────────────────────────────────────────────┤
│ External Services │
│ MaxKB (RAG) │ LLM APIs │ HIS │ MySQL │
└─────────────────────────────────────────────────────────────┘
```
## 🏗️ 架构亮点
### 模型工厂三件套
| 组件 | 职责 | 类比 |
|------|------|------|
| **ProviderFactory** | 注册/创建各供应商客户端 | 汽车工厂 |
| **ModelRouter** | 按场景名路由到对应模型 | GPS 导航 |
| **FallbackChain** | 主模型挂了自动切备用 | 备用轮胎 |
### 场景 → 模型映射（config.yaml 配置）
| 业务场景 | 路由到 | 为什么 |
|----------|--------|--------|
| 病历生成 (emr-generator) | DeepSeek V3 | 中文医学知识丰富，推理链清晰 |
| 处方校验 (prescription) | GPT-4o | 推理严谨，工具调用稳定 |
| 知识问答 (knowledge-qa) | 通义千问 Max | 中文检索效果好 |
| 向量化 (embedding) | text-embedding-3-small | 质量行业领先 |
| 降级兜底 (fallback) | Ollama 本地 | 离线可用，零成本 |
**改模型只需改 config.yaml，不改一行代码。**
## 快速开始
### 1. 启动 MaxKB 知识库
```bash
docker run -d --name maxkb -p 8080:8080 1panel/maxkb
```
访问 http://localhost:8080 上传中医典籍、药典、病历模板。
### 2. 配置（多模型）
编辑 `manifest/config/config.yaml`：
```yaml
llm:
default_provider: "deepseek"
models:
deepseek:
provider: "deepseek"
api_key: "sk-你的key"
base_url: "https://api.deepseek.com"
model: "deepseek-chat"
openai:
provider: "openai"
api_key: "sk-你的key"
base_url: "https://api.openai.com/v1"
model: "gpt-4o"
routes:
emr-generator: "deepseek"
prescription: "openai"
```
### 3. 运行
```bash
go mod tidy
go run main.go
```
### 4. 运行模拟演示
```bash
go run examples/simulation.go
```
将看到：
- 模型工厂创建各供应商客户端
- 路由表展示场景→模型映射
- 降级链工作原理
- 两个完整业务场景的 Agent 生命周期
## API 接口
### 生成病历
```bash
curl -X POST http://localhost:8080/api/v1/emr/generate \
-H "Content-Type: application/json" \
-H "Authorization: Bearer <token>" \
-d '{
"patient_id": "P001",
"chief_complaint": "反复头晕3个月，加重1周",
"history_notes": "患者3个月前无明显诱因出现头晕...",
"allergies": [],
"past_illness": ["慢性胃炎"]
}'
```
### 生成处方
```bash
curl -X POST http://localhost:8080/api/v1/prescription/generate \
-H "Content-Type: application/json" \
-H "Authorization: Bearer <token>" \
-d '{
"patient_id": "P001",
"emr_text": "主诉：反复头晕3个月...舌暗红苔白腻 脉弦滑...",
"diagnosis": "痰湿中阻证",
"age": 45,
"is_pregnant": false,
"allergies": []
}'
```
### 动态切换模型路由（热更新）
```bash
curl -X POST http://localhost:8080/api/v1/models/route \
-H "Content-Type: application/json" \
-d '{"scene": "emr-generator", "provider": "gpt-4o"}'
```
### 查看当前路由表
```bash
curl http://localhost:8080/api/v1/models/routes
```
## 项目结构
```
tcm-agent/
├── main.go # 入口（初始化链：config→llm→agent→router）
├── go.mod
├── Makefile
├── README.md
│
├── examples/
│ └── simulation.go # 场景模拟演示（含模型工厂演示）
│
├── docs/
│ └── agent_lifecycle.md # Agent 生命周期详解
│
├── manifest/
│ ├── config/config.yaml # 配置文件（多模型+路由+降级）
│ └── docker/
│ ├── Dockerfile
│ └── docker-compose.yml
│
├── test/
│ └── agent_test.go # 单元测试（工厂/路由/降级/规则引擎）
│
└── internal/
├── config/config.go # 配置加载（多模型支持）
│
├── llm/ # 🆕 模型工厂层（v2.0 核心）
│ ├── factory.go # 工厂+路由+降级（统一接口定义）
│ ├── deepseek.go # DeepSeek 客户端
│ ├── openai.go # OpenAI 客户端
│ └── other_providers.go # Azure/Ollama/Qwen/Mock
│
├── agent/ # Agent 引擎
│ ├── runner.go # 核心调度器（使用 ModelRouter）
│ ├── emr_agent.go # 病历生成 Agent
│ └── prescription_agent.go # 处方生成 Agent
│
├── tool/ # Agent 工具集
│ ├── maxkb.go # MaxKB 知识库客户端
│ └── agent_tools.go # 工具注册（知识检索/HIS/药典/规则）
│
├── rule/ # 规则引擎
│ └── rule_engine.go # 配伍禁忌/剂量/质控
│
├── handler/ # HTTP 处理器
│ ├── emr_handler.go
│ ├── prescription_handler.go
│ ├── knowledge_handler.go
│ └── agent_handler.go
│
├── router/router.go # 路由注册（含模型管理接口）
├── middleware/middleware.go # 日志/CORS/鉴权
├── dao/dao.go # 数据访问层
└── model/entity/entity.go # 数据模型
```
## 安全设计
### 三层防护
1. **知识防线**：MaxKB 提供权威药典/典籍/指南
2. **规则防线**：代码级硬校验（十八反、十九畏、剂量上限）
3. **人工防线**：医生最终审核（Human-in-the-Loop）
### 审计日志
所有关键操作（生成、修改、审核）全链路记录，满足医疗合规要求。
## 扩展指南
### 接入新模型供应商
只需 3 步：
1. **实现 LLMClient 接口**（`internal/llm/your_provider.go`）：
```go
type YourClient struct{ ... }
func (c *YourClient) Chat(ctx, messages, tools) (*Message, error) { ... }
func (c *YourClient) Embed(ctx, texts) ([][]float32, error) { ... }
// ... 实现其他接口方法
```
2. **注册到工厂**（`internal/llm/factory.go` 的 `NewProviderFactory` 中）：
```go
f.Register("your-provider", createYourClient)
```
3. **在 config.yaml 中添加配置**：
```yaml
llm:
models:
your-model:
provider: "your-provider"
api_key: "your-key"
base_url: "https://api.your-provider.com"
model: "your-model-name"
routes:
emr-generator: "your-model" # 切换病历生成到新模型
```
**无需修改任何业务代码。**
## 测试
```bash
# 运行全部测试
make test
# 运行规则引擎测试
make test-rule
# 运行 Agent 测试
make test-agent
```
## License
MIT
Reference in New Issue Copy Permalink