# 中医知识图谱问答系统 - API接口文档
## 📖 项目简介
基于FastAPI和LangGraph的中医知识图谱智能问答系统，提供RESTful API接口服务。
**技术栈：**
- FastAPI - 高性能Web框架
- LangGraph - 工作流编排
- Neo4j - 图数据库
- FAISS - 向量相似度搜索
- LLM - 大语言模型
---
## 🚀 快速开始
### 1. 启动服务
```bash
cd __005_fastapi
python main.py
```
或使用启动脚本：
```bash
# Windows
start_server.bat
```
### 2. 访问地址
- **API基础地址**: `http://localhost:8000`
- **交互式文档**: `http://localhost:8000/docs` (Swagger UI)
- **ReDoc文档**: `http://localhost:8000/redoc`
---
## 📡 API接口列表
### 1. 健康检查接口
**接口地址**: `GET /`
**功能描述**: 检查服务是否正常运行
**请求参数**: 无
**响应示例**:
```json
{
"status": "ok",
"message": "中医知识图谱问答系统服务运行正常"
}
```
**状态码**:
- `200` - 服务正常
---
### 2. 中医问答接口（核心接口）
**接口地址**: `POST /process`
**功能描述**: 接收用户问题，返回中医知识图谱的智能回答
**Content-Type**: `application/json`
#### 请求参数
| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| input | string | 是 | 用户输入的问题 |
| user_id | string | 是 | 用户唯一标识,用于隔离不同用户的对话历史/记忆。同一用户需在多次请求中传入相同的user_id才能延续上下文,不同用户请使用不同的user_id |
#### 请求示例
```json
{
"input": "人参有什么功效？",
"user_id": "user-123"
}
```
#### 响应参数
| 参数名 | 类型 | 说明 |
|--------|------|------|
| input | string | 用户原始输入 |
| output | string | 系统生成的回答 |
#### 响应示例
**成功响应**:
```json
{
"input": "人参有什么功效？",
"output": "人参具有大补元气、复脉固脱、补脾益肺、生津养血、安神益智等功效。适用于体虚欲脱、肢冷脉微、脾虚食少、肺虚喘咳等症状。"
}
```
**错误响应**:
```json
{
"input": "",
"output": "系统出错了，请重试！"
}
```
#### 状态码
| 状态码 | 说明 |
|--------|------|
| 200 | 请求成功 |
| 500 | 服务器内部错误 |
#### cURL示例
```bash
curl -X POST "http://localhost:8000/process" \
-H "Content-Type: application/json" \
-d '{"input": "感冒了吃什么药？", "user_id": "user-123"}'
```
#### Python示例
```python
import requests
url = "http://localhost:8000/process"
data = {"input": "人参有什么功效？", "user_id": "user-123"}
response = requests.post(url, json=data)
result = response.json()
print(f"问题: {result['input']}")
print(f"回答: {result['output']}")
```
#### JavaScript示例
```javascript
fetch('http://localhost:8000/process', {
method: 'POST',
headers: {
'Content-Type': 'application/json'
},
body: JSON.stringify({
input: '人参有什么功效？',
user_id: 'user-123'
})
})
.then(response => response.json())
.then(data => {
console.log('问题:', data.input);
console.log('回答:', data.output);
})
.catch(error => {
console.error('Error:', error);
});
```
---
### 3. 中医问答接口(流式版)
**接口地址**: `POST /process_stream`
**功能描述**: 与 `/process` 接受同样的请求参数(`input`、`user_id`),但以换行分隔的JSON消息流
(`text/plain`,非严格SSE)返回结果。LangGraph每个节点执行完毕,立即产出一条该节点的状态增量作为
"思考过程";图执行结束后再产出一条最终答案消息。
#### 请求参数
同 `/process`:`input`(必填)、`user_id`(必填)。
#### 响应格式(每行一个JSON对象)
| 消息type | 字段 | 说明 |
|---------|------|------|
| thinking | node, data | 某个节点刚执行完毕,`data`为该节点这一步产生的状态增量(思考过程中间结果) |
| final | input, output | 图执行成功结束,`output`为最终回答 |
| error | input, output | 图执行异常,`output`固定为"系统出错了，请重试！" |
#### 响应示例
```
{"type": "thinking", "node": "语义转写节点", "data": {"input_semantic_trans": "人参有什么功效？"}}
{"type": "thinking", "node": "意图识别节点", "data": {"is_zhongyi_intent": true}}
{"type": "thinking", "node": "实体抽取节点", "data": {"user_input_herbs": ["人参"]}}
...
{"type": "final", "input": "人参有什么功效？", "output": "人参具有大补元气、复脉固脱..."}
```
#### Python示例
```python
import json
import requests
resp = requests.post(
"http://localhost:8000/process_stream",
json={"input": "人参有什么功效？", "user_id": "user-123"},
stream=True,
timeout=120,
)
for line in resp.iter_lines(decode_unicode=True):
if not line:
continue
message = json.loads(line)
if message["type"] == "thinking":
print("思考中:", message["node"], message["data"])
else:
print("最终回答:", message["output"])
```
---
### 4. 静态资源访问
**接口地址**: `GET /picture/{filename}`
**功能描述**: 访问静态图片资源
**路径参数**:
- `filename`: 图片文件名
**示例**:
```
http://localhost:8000/picture/graph.jpg
```
**配置说明**:
静态文件目录通过 `app.mount("/picture", StaticFiles(directory=...))` 挂载
---
## 🔄 工作流程
当用户通过 `/process` 接口提交问题时，系统会执行以下流程：
```
用户输入
↓
意图识别（判断是否中医相关）
↓
├─ 非中医问题 → 直接LLM回答
└─ 中医问题
↓
实体抽取（症状、疾病、方剂、药材等）
↓
FAISS向量匹配（标准化实体名称）
↓
生成Cypher查询语句
↓
验证Cypher语法
↓
执行Neo4j图数据库查询
↓
生成自然语言回答
↓
返回结果
```
---
## 💡 使用示例
### 示例1: 中药查询
**请求**:
```json
{
"input": "人参的性味归经是什么？"
}
```
**响应**:
```json
{
"input": "人参的性味归经是什么？",
"output": "人参性温，味甘、微苦，归脾、肺、心经。"
}
```
### 示例2: 方剂查询
**请求**:
```json
{
"input": "桂枝汤的组成和功效是什么？"
}
```
**响应**:
```json
{
"input": "桂枝汤的组成和功效是什么？",
"output": "桂枝汤由桂枝、芍药、甘草、生姜、大枣组成。具有解肌发表、调和营卫的功效，主治外感风寒表虚证。"
}
```
### 示例3: 症状咨询
**请求**:
```json
{
"input": "我感冒了，有点咳嗽和发热，应该吃什么药？"
}
```
**响应**:
```json
{
"input": "我感冒了，有点咳嗽和发热，应该吃什么药？",
"output": "根据您的症状（感冒、咳嗽、发热），建议可以考虑以下方剂：银翘散、桑菊饮等。但请注意，具体用药需要结合您的体质和病情，建议咨询专业中医师。"
}
```
### 示例4: 非中医问题
**请求**:
```json
{
"input": "今天天气怎么样？"
}
```
**响应**:
```json
{
"input": "今天天气怎么样？",
"output": "抱歉，我无法提供天气信息。我是一个中医知识图谱问答系统，主要回答中医药相关的问题，如中药、方剂、症状、疾病等。如果您有中医方面的问题，欢迎提问！"
}
```
---
## ⚙️ 配置说明
### 环境变量配置
在 `common/.env` 文件中配置以下参数：
```env
# 大模型配置
MODEL_API_KEY=your_api_key
MODEL_BASE_URL=https://api.example.com
MODEL_NAME=gpt-3.5-turbo
# Neo4j数据库配置
NEO4J_URI=bolt://localhost:7687
NEO4J_USER=neo4j
NEO4J_PASSWORD=your_password
# Embedding模型配置
EMBEDDING_MODEL_PATH=./bge-large-zh-v1.5
```
### FAISS索引路径
FAISS索引文件路径配置在以下文件中：
- `__004__langgraph_more_nodes/nodes/match_entity_node.py`
- `__003__create__information/__003__faiss_embedding.py`
**注意**: 由于FAISS库在Windows中文路径下的兼容性问题，建议使用英文路径存储FAISS索引文件。
```python
index_path = r"E:\ctm_index\nero4j_embedding_faiss.index"
id2text_path = r"E:\ctm_index\nero4j_embedding_faiss_id2text.pkl"
```
---
## 🔧 开发指南
### 项目结构
```
__005_fastapi/
├── main.py # FastAPI主程序
├── start_server.bat # Windows启动脚本
├── test_api.py # API测试脚本
├── quick_test.py # 快速诊断脚本
├── README.md # 使用说明
└── API_INTERFACE.md # API接口文档（本文件）
__004__langgraph_more_nodes/
├── full_workflow.py # LangGraph工作流
├── agent_state.py # Agent状态定义
└── nodes/ # 各个处理节点
├── zhongyi_intent_node.py # 意图识别
├── extract_entity_node.py # 实体抽取
├── match_entity_node.py # 实体匹配
├── generate_cypher_node.py # Cypher生成
├── check_cypher_node.py # Cypher验证
├── run_cypher_node.py # Cypher执行
└── generate_answer_node.py # 答案生成
```
### 添加新接口
在 `main.py` 中添加新的路由：
```python
from fastapi import FastAPI
from pydantic import BaseModel
app = FastAPI()
class QueryRequest(BaseModel):
input: str
max_retries: int = 3
@app.post("/api/custom")
async def custom_endpoint(request: QueryRequest):
# 你的业务逻辑
result = process_query(request.input)
return {"result": result}
```
### 错误处理
系统会自动捕获异常并返回友好的错误信息：
```python
try:
data = await request.json()
input_text = data.get("input", "")
output = await zhongyi_response(input_text)
result = {
"input": input_text,
"output": output
}
except Exception as e:
import traceback
traceback.print_exc()
result = {
"input": "",
"output": "系统出错了，请重试！"
}
```
---
## 📊 性能优化
### 1. 超时设置
对于长时间运行的查询，建议在客户端设置合理的超时时间：
```python
# Python requests示例
response = requests.post(url, json=data, timeout=120) # 120秒超时
```
### 2. 并发处理
FastAPI天然支持异步处理，可以同时处理多个请求。
### 3. 缓存策略
对于频繁查询的问题，可以实现缓存机制：
```python
from functools import lru_cache
@lru_cache(maxsize=1000)
def cached_zhongyi_response(input_text: str):
return zhongyi_response(input_text)
```
---
## ❓ 常见问题
### Q1: 服务启动失败怎么办？
**A**: 检查以下几点：
1. 确认端口8000未被占用
2. 检查 `common/.env` 配置文件是否正确
3. 确认所有依赖已安装：`pip install -r requirements.txt`
4. 查看控制台错误信息
### Q2: 响应时间过长怎么办？
**A**: 可能的原因：
1. LLM模型响应慢 - 考虑使用更快的模型
2. FAISS索引较大 - 优化索引结构
3. Neo4j查询复杂 - 优化Cypher语句
4. 首次加载需要初始化 - 后续请求会更快
### Q3: 如何修改端口号？
**A**: 修改 `main.py` 最后一行：
```python
uvicorn.run(app, host="0.0.0.0", port=8001) # 改为8001端口
```
### Q4: 如何部署到生产环境？
**A**: 推荐使用以下方式之一：
**方式1: 使用Gunicorn + Uvicorn**
```bash
pip install gunicorn
gunicorn main:app -w 4 -k uvicorn.workers.UvicornWorker -b 0.0.0.0:8000
```
**方式2: 使用Docker**
```dockerfile
FROM python:3.10
WORKDIR /app
COPY . .
RUN pip install -r requirements.txt
CMD ["uvicorn", "main:app", "--host", "0.0.0.0", "--port", "8000"]
```
**方式3: 使用Nginx反向代理**
```nginx
server {
listen 80;
server_name your-domain.com;
location / {
proxy_pass http://127.0.0.1:8000;
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
}
}
```
### Q5: 如何监控API使用情况？
**A**: 可以添加日志记录：
```python
import logging
from datetime import datetime
logging.basicConfig(filename='api.log', level=logging.INFO)
@app.post("/process")
async def process(request: Request):
start_time = datetime.now()
data = await request.json()
# 记录请求
logging.info(f"Request: {data.get('input')} at {start_time}")
# ... 业务逻辑
end_time = datetime.now()
duration = (end_time - start_time).total_seconds()
# 记录响应时间和结果
logging.info(f"Response time: {duration}s")
return JSONResponse(content=result)
```
---
## 🔐 安全建议
### 1. 添加API认证
```python
from fastapi import Depends, HTTPException
from fastapi.security import HTTPBearer, HTTPAuthorizationCredentials
security = HTTPBearer()
async def verify_token(credentials: HTTPAuthorizationCredentials = Depends(security)):
if credentials.credentials != "your-secret-token":
raise HTTPException(status_code=401, detail="Invalid token")
return credentials
@app.post("/process")
async def process(request: Request, credentials: dict = Depends(verify_token)):
# 你的业务逻辑
pass
```
### 2. 限制请求频率
```python
from slowapi import SlowAPIMiddleware
from slowapi.errors import RateLimitExceeded
app.state.limiter = Limiter(default_rate_limit="10/minute")
app.add_exception_handler(RateLimitExceeded, _rate_limit_exceeded_handler)
@app.post("/process")
@limiter.limit("5/minute")
async def process(request: Request):
# 每分钟最多5次请求
pass
```
### 3. 输入验证
```python
from pydantic import BaseModel, Field
class QueryRequest(BaseModel):
input: str = Field(..., min_length=1, max_length=500, description="用户问题")
```
---
## 📝 更新日志
### v1.0.0 (2024-01-01)
- ✅ 初始版本发布
- ✅ 实现基本的中医问答接口
- ✅ 集成LangGraph工作流
- ✅ 支持Neo4j图数据库查询
- ✅ 支持FAISS向量相似度搜索
- ✅ 提供Swagger交互式文档
---
## 📞 技术支持
如有问题或建议，请联系：
- 📧 Email: [your-email@example.com]
- 💬 Issues: [GitHub Issues链接]
- 📖 文档: [项目Wiki链接]
---
## 📄 License
本项目仅供学习和研究使用。
---
## 🌟 附录
### A. 完整的请求-响应流程图
```
Client Server Backend
| | |
|-- POST /process ------------->| |
| {input: "人参功效"} | |
| |-- 意图识别 ------------------>|
| | |
| |-- 实体抽取 ------------------>|
| | |
| |-- FAISS匹配 ---------------->|
| | |
| |-- 生成Cypher --------------->|
| | |
| |-- 执行Neo4j查询 ------------>|
| | |
| |-- LLM生成回答 -------------->|
| | |
|<-- 200 OK --------------------| |
| {input, output} | |
| | |
```
### B. 支持的实体类型
| 实体类型 | 英文标识 | 示例 |
|---------|---------|------|
| 症状 | Symptom | 咳嗽、发热、失眠 |
| 疾病 | Disease | 风寒感冒、脾虚泄泻 |
| 方剂 | Formula | 桂枝汤、麻黄汤 |
| 药材 | Herb | 人参、黄芪、当归 |
| 功效 | Effect | 清热、补气、祛湿 |
| 出处 | Source | 《伤寒论》《本草纲目》 |
### C. 常用测试问题
```
1. 人参有什么功效？
2. 桂枝汤的组成是什么？
3. 感冒了吃什么药？
4. 如何治疗失眠？
5. 黄芪和人参有什么区别？
6. 《伤寒论》中有哪些经典方剂？
7. 咳嗽有哪些中药可以治疗？
8. 补气的中药有哪些？
```
---
**最后更新时间**: 2024-01-01
**文档版本**: v1.0.0