项目简介

这是一个基于 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 运行，并创建数据库/账号（例）：

     CREATE DATABASE allm DEFAULT CHARACTER SET utf8mb4;
     ALTER USER 'root'@'localhost' IDENTIFIED BY '*******';
     GRANT ALL PRIVILEGES ON allm.* TO 'root'@'localhost';
     FLUSH PRIVILEGES;
     

   • 启动前设置环境变量：

     export DATABASE_URL="******"
     

3. 迁移（首次必跑）

   python -m alembic upgrade head
   

4. 启动服务

   # 启动项目命令
   python3 -m uvicorn main:app --host 0.0.0.0 --port 8000 --reload
   

5. 查看日志

   tail -f /tmp/uvicorn.log