knowledge-tools

知识工具服务

项目结构

knowledge-tools/
├── src/                    # 源代码目录
│   ├── api/               # API接口模块
│   │   └── main.py        # FastAPI主应用
│   ├── agent/             # LangGraph Agent模块
│   │   └── query_agent.py # 查询生成Agent
│   ├── tools/             # 工具模块
│   │   ├── query_tool.py  # 查询工具
│   │   ├── prompts.py     # Prompt模板
│   │   └── scheduler.py   # 任务调度器
│   ├── database/          # 数据库模块
│   │   ├── connection.py  # 数据库连接管理
│   │   └── models.py      # 数据库模型和DAO
│   └── models/            # 数据模型
│       └── schemas.py     # Pydantic模型
├── logs/                  # 日志目录
├── start.sh              # 启动脚本
├── stop.sh               # 停止脚本
├── main.py               # 主程序入口
├── requirements.txt      # Python依赖
├── app.pid              # 进程ID文件
└── .env                 # 环境变量配置文件

功能特性

• 🚀 RESTful API: 基于FastAPI构建的高性能API服务
• 🤖 智能Agent: 使用LangGraph构建的查询生成Agent
• 🗄️ 数据库支持: MySQL数据库存储任务记录和状态跟踪
• ⚡ 异步处理: 任务异步处理，提高系统响应性能
• ⏰ 定时调度: 每分钟自动处理待执行任务
• 🔧 模块化设计: 清晰的模块分离，便于维护和扩展
• 📝 详细日志: 完整的日志记录和错误处理
• 🛠️ 便捷脚本: 一键启动/停止服务脚本

快速开始

1. 环境准备

# 克隆项目（如果从git仓库）
git clone <repository-url>
cd knowledge-tools

# 创建虚拟环境
python3 -m venv venv
source venv/bin/activate  # Linux/Mac
# 或
venv\Scripts\activate     # Windows

2. 安装依赖

pip install -r requirements.txt

3. 配置环境变量

# 复制环境变量示例文件
cp env.example .env

# 编辑.env文件，设置你的OpenAI API密钥
vim .env

4. 启动服务

# 使用脚本启动（推荐）
./start.sh

# 或直接使用Python
python main.py

5. 测试服务

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

# 生成查询词（异步处理）
curl -X POST "http://localhost:8079/generate-queries" \
     -H "Content-Type: application/json" \
     -d '{"question": "如何学习Python编程"}'

# 查询任务状态
curl http://localhost:8079/task/1703123456789

# 运行异步处理测试（需要先创建测试脚本）
# python test_async_processing.py

API接口

健康检查

• GET /health
• 返回服务状态

生成查询词（异步处理）

• POST /generate-queries

• 请求体：

  {
  "question": "用户的问题"
  }
  

  • 响应（立即返回，状态为待执行）： json { "task_id": 1703123456789, "queries": [], "original_question": "原始问题", "total_count": 0, "status": 0 }

• 说明：接口立即返回任务ID，实际处理由后台定时任务完成

获取任务信息

• GET /task/{task_id}

• 响应：

  {
  "task_id": 1703123456789,
  "question": "用户的问题",
  "queries": ["查询词1", "查询词2", "..."],
  "status": 2,
  "status_text": "成功"
  }
  

  • 状态说明：
  • 0 - 待执行：任务已创建，等待后台处理
  • 1 - 执行中：任务正在处理中
  • 2 - 成功：任务处理完成，已生成查询词
  • 3 - 失败：任务处理失败

  获取任务列表

  • GET /tasks?status=2&limit=10
  • 参数：
  • status: 任务状态筛选（0-待执行，1-执行中，2-成功，3-失败）
  • limit: 限制数量
  • 响应： json { "tasks": [...], "total": 10 }

服务管理

启动服务

./start.sh

停止服务

./stop.sh

查看日志

tail -f logs/app.log

异步任务处理

工作流程

1. 任务提交: 调用 /generate-queries 接口提交问题
2. 立即返回: 接口立即返回任务ID和待执行状态
3. 后台处理: 定时调度器每分钟检查并处理待执行任务
4. 状态查询: 通过 /task/{task_id} 接口查询任务处理状态

任务状态

• 0 - 待执行: 任务已创建，等待处理
• 1 - 执行中: 任务正在处理中
• 2 - 成功: 任务处理完成，已生成查询词
• 3 - 失败: 任务处理失败

测试异步处理

可以创建测试脚本验证异步处理功能：

# 创建测试脚本后运行
python test_async_processing.py

配置说明

主要配置项在 .env 文件中：

# Gemini API配置
GEMINI_API_KEY=your_gemini_api_key_here
GEMINI_MODEL=gemini-1.5-pro

# 数据库配置
DB_HOST=rm-bp13g3ra2f59q49xs.mysql.rds.aliyuncs.com
DB_PORT=3306
DB_USER=wqsd
DB_PASSWORD=wqsd@2025
DB_NAME=ai_knowledge
DB_CHARSET=utf8

# 服务配置
HOST=0.0.0.0
PORT=8079
DEBUG=True

# 日志配置
LOG_LEVEL=INFO
LOG_FILE=logs/app.log

开发说明

模块说明

1. API模块 (src/api/): 负责HTTP接口和路由处理
2. Agent模块 (src/agent/): 包含LangGraph Agent逻辑
3. 工具模块 (src/tools/): 定义各种工具、Prompt模板和任务调度器
4. 数据库模块 (src/database/): 数据库连接、模型和DAO操作
5. 模型模块 (src/models/): 定义数据模型和Schema

扩展开发

• 添加新工具：在 src/tools/ 目录下创建新的工具类
• 修改Prompt：编辑 src/tools/prompts.py 文件
• 调整Agent逻辑：修改 src/agent/query_agent.py 文件
• 添加新接口：在 src/api/main.py 中添加新的路由
• 调整调度策略：修改 src/tools/scheduler.py 文件

数据库表结构

项目使用MySQL数据库存储任务信息，需要创建以下表：

CREATE TABLE `knowledge_suggest_query` (
  `question` text COMMENT '问题',
  `task_id` bigint(20) NOT NULL COMMENT '任务id',
  `querys` mediumtext COMMENT '产出的query词，json格式',
  `status` int(11) DEFAULT NULL COMMENT '0:待执行；1:执行中；2:成功； 3:失败；',
  PRIMARY KEY (`task_id`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8 COMMENT='生成query词任务';