LongjoeAgent

龙嘉软件AI助手项目

项目简介

龙嘉软件AI助手是一个基于FastAPI和LangChain构建的智能对话系统，提供聊天、OCR识别、文档处理等AI功能。项目采用模块化设计，支持多用户并发处理，具备完善的工具管理和缓存机制。

项目结构

LongjoeAgent/
├── api/                    # API接口层
│   ├── models.py          # 数据模型定义
│   └── routes.py          # 路由定义
├── config/                # 配置文件
│   ├── template_config.json   # 单据识别模板提示词配置
│   ├── tool_config.json   # 工具提示词配置
├── core/                  # 核心业务逻辑
│   ├── agent.py           # LangChain Agent创建
│   ├── agent_manager.py   # Agent管理器
│   ├── chat_service.py    # 聊天服务
│   ├── document_processor/ # 文档处理模块
│   ├── ocr_service.py     # OCR服务
│   └── lifespan_manager.py # 生命周期管理
├── tools/                 # 工具模块
│   ├── base_tools.py      # 工具类公用方法
│   ├── knowledge_tools.py # 知识库工具
│   ├── sale_tools.py      # 销售工具
│   ├── ware_tools.py      # 库存工具
│   └── tool_factory.py    # 工具工厂
├── middlewares/           # 中间件
├── utils/                 # 工具类
├── chat_logs/            # 聊天日志
├── app.py                # 主应用入口
├── requirements.txt      # 依赖包
├── cythonize.py          # 编译工具
└── setup.py             # 编译配置

主要功能

1. 智能聊天

• 支持多用户并发对话
• 基于LangChain的智能Agent
• 工具调用和思维链展示
• 对话历史管理

2. OCR识别

• 支持图片Base64格式识别
• 集成PaddleOCR服务
• 发票、单据等文档识别
• 结构化数据提取

3. 文档处理

• 多类型文档模板支持
• 自动化的单据创建
• 文档内容解析和结构化

4. 工具管理

• 动态工具发现和加载
• 知识库查询工具
• 销售数据获取工具
• 可扩展的工具框架

技术栈

• 后端框架: FastAPI
• AI框架: LangChain, LangGraph
• OCR服务: PaddleOCR
• 缓存管理: 本地缓存
• 日志系统: 自定义日志记录
• 部署: Uvicorn + 多进程

快速开始

环境要求

• Python 3.8+
• 安装依赖包

安装步骤

1. 安装python 3.13.7 https://www.python.org/ftp/python/3.13.7/python-3.13.7-amd64.exe

2. 克隆项目

3. 创建并激活虚拟环境

   • 进入项目目录

     cd your_project_folder
     

   • 创建名为 venv 的虚拟环境

     python -m venv venv
     

   • 激活环境

     venv\Scripts\activate
     

4. 在虚拟环境中安装依赖

   pip install -r requirements.txt -i https://mirrors.aliyun.com/pypi/simple/
   

5. 配置DEEPSEEK_API_KEY 参考.env.development.example创建 .env.development 文件并配置DEEPSEEK_API_KEY

6. 获取设备码, 并向耀申请注册码

   python get_device_id.py
   

7. 配置注册码 参考.registration.example创建 .registration 文件并配置REGISTRATION_CODE

8. 启动服务

   python app.py
   

9. 服务启动后访问 健康检查: http://localhost:8888/health, 确认服务启动成功

API接口

主要接口

1. 聊天接口

• 路径: POST /chat
• 功能: 处理用户消息并返回AI回复
• 请求体: json { "message": "用户消息", "thread_id": "会话ID", "username": "用户名", "backend_url": "后端URL", "token": "认证令牌" }

2. OCR识别接口

• 路径: POST /ocr
• 功能: 识别图片中的文字
• 请求体: json { "image": "Base64图片数据", "type": "图片类型" }

3. 单据创建接口

• 路径: POST /message_create_bill
• 功能: 通过文本消息辅助创建单据
• 请求体: json { "message": "单据描述", "document_type": "单据类型" }

工具配置

项目目前支持以下工具：

• 知识库工具: 查询知识库内容
• 销售工具: 获取销售数据
• 库存工具: 通过工具工厂动态加载

开发指南

添加新工具

1. 在 tools/ 目录下创建新的工具文件,以 _tools.py 结尾,通常一个文件对应一个模块的工具
2. 使用 @tool 装饰器标记工具函数,或使用 tool 类定义工具(参考ware_tools.py)
3. 工具函数需要包含 name 和 description 属性
4. 工具工厂会自动发现并加载新工具
5. 工具的提示词可以通过json配置,在config\tool_config.json中定义,重新启动服务后生效

扩展API接口

1. 在 api/routes.py 中添加新的路由
2. 在 api/models.py 中定义数据模型
3. 在相应的服务模块中实现业务逻辑

部署说明

生产环境部署

1. 生成依赖包 requirements.txt

   pipreqs . --encoding=utf8 --force
   

2. 使用setup.py编译项目

   python cythonize.py
   

3. 使用Uvicorn启动服务

   uvicorn app:app --host 0.0.0.0 --port 8888 --workers 4
   

性能优化建议

• 调整线程池大小（在chat_service.py中配置）
• 优化缓存策略（在agent_manager.py中配置）
• 监控内存使用和响应时间

故障排除

常见问题

1. 工具加载失败

   • 检查工具函数是否正确定义
   • 确认工具函数有name和description属性

2. OCR识别失败

   • 检查OCR服务连接
   • 验证图片格式和大小

3. 内存泄漏

   • 定期清理缓存
   • 监控内存使用情况

日志查看

日志文件位于 chat_logs/ 目录，包含详细的运行信息。

许可证

本项目仅供龙嘉软件内部使用。

联系方式

如有问题请联系项目维护团队。

---

最后更新: 2026年1月