83 lines
4.5 KiB
Markdown
83 lines
4.5 KiB
Markdown
## 项目简介
|
||
|
||
这是一个基于 **FastAPI** 的后端服务，提供「智能工作流」「知识库问答」「数据库智能查询」等能力，前端可以通过 REST API 调用这些能力。
|
||
|
||
### 主要目录结构（前端常用关注点）
|
||
- **`th_agenter/api/endpoints/`**：对外 HTTP 接口（路由）
|
||
- `auth.py`：登录、鉴权相关接口
|
||
- `users.py` / `roles.py`：用户与角色管理
|
||
- `chat.py` / `smart_chat.py` / `smart_query.py`：普通聊天、智能问答、智能查询
|
||
- `knowledge_base.py`：知识库管理（上传文档、构建向量库、检索）
|
||
- `workflow.py`：工作流定义、获取、执行等接口
|
||
- **`th_agenter/services/`**：业务逻辑层，API 绝大部分会调用这里
|
||
- `workflow_engine.py` / `smart_workflow.py`：工作流执行引擎与智能工作流封装
|
||
- `knowledge_chat.py` / `document_processor.py` / `embedding_factory.py`：知识库问答、向量检索、文档处理
|
||
- `auth.py` / `user.py` 等：账号、权限等业务
|
||
- **`th_agenter/schemas/`**：Pydantic 模型，定义接口请求/响应的数据结构
|
||
- **`th_agenter/models/`**：SQLAlchemy 模型，对应数据库表结构
|
||
- **`th_agenter/core/`**：应用配置、上下文、中间件、异常处理、权限控制等
|
||
- **`th_agenter/db/`**：数据库连接、基础模型、Alembic 迁移脚本封装
|
||
- **`utils/`**：日志（`util_log.py`）、文件、环境、异常等通用工具
|
||
- **`scripts/`**：本地开发相关脚本（如 `start_local.sh`、`install_mysql.sh` 等）
|
||
- **`data/`**：本地数据与向量库文件（如 Chroma 存储）
|
||
|
||
### 核心能力与典型接口
|
||
- **鉴权与用户体系**
|
||
- 登录、Token 相关接口在 `auth.py` 中定义，一般使用 Bearer Token 放在 `Authorization` 头里。
|
||
- 用户、角色、权限相关接口在 `users.py`、`roles.py`、`core/simple_permissions.py` 等文件中。
|
||
|
||
- **聊天与智能问答**
|
||
- 普通聊天接口：`chat.py`
|
||
- 智能聊天 / 智能问答：`smart_chat.py`、`smart_query.py`、`langchain_chat.py`
|
||
- 有些接口可能支持流式返回或长连接（如 SSE），可直接查看对应 endpoint 的返回类型。
|
||
|
||
- **知识库管理**
|
||
- 相关接口在 `knowledge_base.py` 中，业务逻辑在 `services/knowledge_base.py`、`services/document_processor.py`、`services/knowledge_chat.py` 中。
|
||
- 支持上传文档（通常是 multipart）、构建向量库、基于文档进行问答。
|
||
|
||
- **工作流引擎**
|
||
- 路由在 `workflow.py`，核心执行逻辑在 `services/workflow_engine.py`、`services/smart_workflow.py`、`services/workflow_engine.py` 中。
|
||
- 支持定义工作流、查询工作流详情、执行工作流，并在执行过程中写入日志/上下文（如 `session.desc`）。
|
||
|
||
### 前端对接小提示
|
||
- **接口文档**：服务启动后可以访问 `http://localhost:8000/docs` 查看 Swagger 文档（或 `/redoc`）。
|
||
- **认证方式**：大多需要携带 `Authorization: Bearer <token>`，具体登录接口与返回字段可在 `auth.py` 与对应 `schemas` 中查看。
|
||
- **上传文件**：知识库相关接口通常使用 `multipart/form-data`，前端可以用 `FormData` 构造请求。
|
||
- **错误格式**：统一使用 FastAPI 的 JSON 错误响应格式，并在 `core/exceptions.py` 中做了封装，前端可以根据 `code`/`detail` 等字段做统一处理。
|
||
- **调试追踪**：很多服务里会给 `session.desc` 等字段写入本次请求的行为描述（例如「获取工作流引擎」），方便在日志中排查问题。
|
||
|
||
## 启动项目（本地）
|
||
|
||
1. 准备环境
|
||
- 推荐 Python 3.11+
|
||
- 创建并激活虚拟环境：`python3 -m venv .venv && source .venv/bin/activate`
|
||
- 依赖安装：`pip install -r requirements.txt`（若 requirements.txt 为 UTF-16，需要先转 UTF-8）
|
||
|
||
2. 配置数据库
|
||
- 确保本地 MySQL 运行，并创建数据库/账号（例）：
|
||
```sql
|
||
CREATE DATABASE allm DEFAULT CHARACTER SET utf8mb4;
|
||
ALTER USER 'root'@'localhost' IDENTIFIED BY '*******';
|
||
GRANT ALL PRIVILEGES ON allm.* TO 'root'@'localhost';
|
||
FLUSH PRIVILEGES;
|
||
```
|
||
- 启动前设置环境变量：
|
||
```bash
|
||
export DATABASE_URL="******"
|
||
```
|
||
|
||
3. 迁移（首次必跑）
|
||
```bash
|
||
python -m alembic upgrade head
|
||
```
|
||
|
||
4. 启动服务
|
||
```bash
|
||
# 启动项目命令
|
||
python3 -m uvicorn main:app --host 0.0.0.0 --port 8000 --reload
|
||
```
|
||
5. 查看日志
|
||
```bash
|
||
tail -f /tmp/uvicorn.log
|
||
```
|