# 龙嘉软件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. 创建并激活虚拟环境
   进入项目目录
   ```bash
   cd your_project_folder
   ```
   
   创建名为 venv 的虚拟环境
   ```bash
   python -m venv venv
   ```
   
   激活环境
   ```bash
   venv\Scripts\activate
   ```

4. 在虚拟环境中安装依赖
```bash
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. 获取设备码, 并向耀申请注册码
```bash
python get_device_id.py
```

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


8. 启动服务
```bash
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
```bash
pipreqs . --encoding=utf8 --force
```

1. 使用setup.py编译项目
```bash
python cythonize.py
```

1. 使用Uvicorn启动服务
```bash
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月*