citu_vanna/test/custom_react_agent/doc/FLASK_MIGRATION.md

Flask API 迁移说明

📋 迁移概述

已将 Custom React Agent API 从 FastAPI 迁移到 Flask，保持了相同的功能和接口，但使用了不同的 Web 框架。

🔄 主要变化

1. 依赖包变化

# 旧版本 (FastAPI)
pip install fastapi uvicorn aiohttp

# 新版本 (Flask)
pip install flask aiohttp

2. 框架特性差异

特性	FastAPI	Flask
自动API文档	✅ 自动生成 /docs	❌ 无自动文档
请求验证	✅ Pydantic 自动验证	⚠️ 手动验证
异步支持	✅ 原生支持	⚠️ 需要 asyncio.run()
类型提示	✅ 完整支持	⚠️ 基础支持
性能	🚀 更高	📊 中等
学习曲线	📈 中等	📊 简单

3. 代码结构变化

路由定义

# FastAPI
@app.post("/api/chat", response_model=ChatResponse)
async def chat_endpoint(request: ChatRequest):
    ...

# Flask
@app.route("/api/chat", methods=["POST"])
def chat_endpoint():
    data = request.get_json()
    ...

响应格式

# FastAPI
return ChatResponse(code=200, message="成功", data=result)

# Flask
return jsonify({"code": 200, "message": "成功", "data": result})

错误处理

# FastAPI
raise HTTPException(status_code=400, detail="错误信息")

# Flask
return jsonify({"error": "错误信息"}), 400

✅ 保持不变的功能

1. API 接口: 所有端点路径和参数保持不变
2. 响应格式: JSON 响应结构完全一致
3. 功能逻辑: Agent 处理逻辑无任何变化
4. 会话管理: Thread ID 管理机制保持原样
5. 错误处理: 错误代码和消息保持一致

🚀 启动方式

Flask 版本启动

# 方式1：直接运行
python api.py

# 方式2：使用 flask 命令
export FLASK_APP=api.py
flask run --host=0.0.0.0 --port=8000

测试验证

# 健康检查
curl http://localhost:8000/health

# 功能测试
python test_api.py

🔧 开发者注意事项

1. 异步函数调用

# Flask 中调用异步 Agent 方法
agent_result = asyncio.run(_agent_instance.chat(...))

2. 请求数据验证

# 手动验证替代 Pydantic
def validate_request_data(data):
    errors = []
    if not data.get('question'):
        errors.append('问题不能为空')
    # ... 更多验证
    if errors:
        raise ValueError('; '.join(errors))

3. CORS 支持

# 暂时不启用跨域支持
# 如果需要跨域支持，可以安装 flask-cors
# pip install flask-cors

📊 性能考虑

1. 单线程处理: Flask 默认单线程，高并发时需要配置 WSGI 服务器
2. 内存使用: 相比 FastAPI 略低
3. 启动速度: 更快的启动时间
4. 开发效率: 更简单的调试和开发

🛠️ 生产部署建议

使用 Gunicorn

pip install gunicorn
gunicorn -w 4 -b 0.0.0.0:8000 api:app

使用 uWSGI

pip install uwsgi
uwsgi --http :8000 --wsgi-file api.py --callable app --workers 4

🐛 故障排除

常见问题

1. 异步函数调用错误

   • 确保使用 asyncio.run() 包装异步调用

2. CORS 错误

   • 当前未启用跨域支持
   • 如需跨域支持，可安装 pip install flask-cors

3. 端口占用

   # 查看端口占用
   netstat -an | grep 8000
   

   ---

   迁移完成: Flask 版本已完全实现所有 FastAPI 功能，接口保持 100% 兼容。