knowledge-agent

Knowledge Agent API

基于 FastAPI + LangGraph 的智能内容识别和结构化处理服务。支持通过API输入指令执行Agent。

🚀 快速开始

1. 安装依赖

pip install -r requirements.txt

2. 启动服务

方式一：使用启动脚本（推荐）

./start_service.sh  # 启动主服务
./start_api.sh      # 启动API服务

方式二：直接运行

python3 agent.py  # 运行Agent
python3 api.py    # 运行API服务

方式三：使用 uvicorn

uvicorn agent:app --host 0.0.0.0 --port 8080 --reload  # 主服务
uvicorn api:app --host 0.0.0.0 --port 8000 --reload     # API服务

3. 访问服务

• 服务地址: http://localhost:8080
• API文档: http://localhost:8080/docs
• 健康检查: http://localhost:8080/health

📚 API 接口

POST /execute

通过API执行Agent处理用户指令

请求体:

{
  "instruction": "你的指令内容"
}

响应:

{
  "status": "success",
  "result": "Agent执行结果..."
}

GET /

API服务健康检查

响应:

{
  "message": "Knowledge Agent API 服务已启动，请使用 /execute 端点执行Agent"
}

POST /parse

同步解析内容处理

请求体:

{
  "requestId": "your_request_id"
}

响应:

{
  "requestId": "your_request_id",
  "processed": 5,
  "success": 4,
  "details": [
    {
      "index": 1,
      "dbInserted": true,
      "identifyError": null,
      "status": "success"
    }
  ]
}

POST /parse/async

异步解析内容处理（后台任务）

请求体:

{
  "requestId": "your_request_id"
}

响应:

{
  "requestId": "your_request_id",
  "status": "processing",
  "message": "任务已提交到后台处理"
}

GET /health

健康检查接口

响应:

{
  "status": "healthy",
  "timestamp": 1703123456.789
}

🔧 配置

环境变量

• GEMINI_API_KEY: Gemini API 密钥（必需）

LangSmith 配置

系统支持 LangSmith 追踪功能，可以通过 .env 文件配置：

1. 在 .env 文件中配置： ```bash

   启用 LangSmith 追踪

   LANGCHAIN_TRACING_V2=true

LangSmith API 端点

LANGCHAIN_ENDPOINT=https://api.smith.langchain.com

你的 LangSmith API 密钥

LANGCHAIN_API_KEY=your_langsmith_api_key_here

项目名称（可选）

LANGCHAIN_PROJECT=knowledge-agent

3. 重启服务即可生效

**注意**: 如果没有配置 `.env` 文件或相关环境变量，系统将自动禁用 LangSmith 追踪以避免网络连接错误。

### 数据库配置

在 `utils/mysql_db.py` 中配置数据库连接信息。

## 📁 项目结构

knowledge-agent/ ├── agent.py # FastAPI + LangGraph 主服务文件 ├── agent_tools.py # 核心工具类 ├── gemini.py # Gemini API 处理器 ├── indentify/ # 内容识别模块 │ ├── image_identifier.py # 图像识别 │ ├── video_identifier.py # 视频识别 │ └── indentify.py # 识别主逻辑 ├── structure/ # 结构化处理模块 │ └── structure_processor.py ├── utils/ # 工具模块 │ ├── mysql_db.py # 数据库操作 │ ├── logging_config.py # 日志配置 │ └── file.py # 文件操作 ├── prompt/ # 提示词模板 ├── requirements.txt # 依赖包列表 └── start_service.sh # 启动脚本

## 🎯 核心功能

1. **内容识别**: 支持图像和视频的智能识别
2. **结构化处理**: 使用 Gemini API 进行内容结构化
3. **数据存储**: 自动存储处理结果到数据库
4. **异步处理**: 支持后台异步任务处理
5. **RESTful API**: 现代化的 HTTP API 接口
6. **工作流管理**: 基于 LangGraph 的强大流程控制
7. **状态管理**: 完整的处理状态跟踪和错误处理
8. **流程恢复**: 服务启动时自动恢复中断的处理流程
9. **Agent API**: 支持通过API直接执行Agent处理指令

## 🔄 流程恢复功能

服务启动时会自动检查并恢复中断的处理流程：

### 恢复机制

1. **解析流程恢复**: 自动查找 `parsing_status=1` 的请求，重新调用 `/parse/async` 接口
2. **提取流程恢复**: 自动查找 `extraction_status=1` 的请求，重新调用 `/extract` 接口
3. **扩展流程恢复**: 自动查找 `expansion_status=1` 的请求，重新调用 `/expand` 接口

### 特性

- **智能重试**: 使用指数退避算法进行重试，最多重试3次
- **并发安全**: 避免重复处理同一请求
- **错误处理**: 完善的错误日志记录和异常处理
- **延迟启动**: 等待服务完全启动后再进行恢复

### 测试流程恢复功能

```bash
# 创建测试数据
python3 test_restore.py --create-data

# 运行测试
python3 test_restore.py --test

# 清理测试数据
python3 test_restore.py --cleanup

📝 API使用示例

Python示例

import requests

# API服务地址
api_url = "http://localhost:8000/execute"

# 发送请求
response = requests.post(
    api_url,
    json={"instruction": "分析以下内容并提取关键信息：..."},
)

# 处理响应
if response.status_code == 200:
    result = response.json()
    print(f"状态: {result['status']}")
    print(f"结果: {result['result']}")
else:
    print(f"请求失败: {response.status_code}")

cURL示例

curl -X POST http://localhost:8000/execute \
  -H "Content-Type: application/json" \
  -d '{"instruction": "分析以下内容并提取关键信息：..."}'

🚨 注意事项

1. 确保设置了正确的 GEMINI_API_KEY 环境变量
2. 确保数据库连接配置正确
3. 服务默认监听 8080 端口，可通过参数修改

🔍 故障排除

常见问题

1. 导入错误: 确保所有依赖已正确安装
2. 数据库连接失败: 检查数据库配置和网络连接
3. Gemini API 错误: 验证 API 密钥是否正确

日志查看

服务运行时会输出详细日志，包括：

• 请求处理状态
• 错误信息
• 处理进度
• 性能指标