Project-S

基于 FastAPI 的多客户端 AI 应用后端，支持多 AI 角色对话、记忆系统、文件上传、实时通话信令。

多客户端架构

本项目包含三个子项目：

项目	路径	技术栈	平台
后端 API	Project-S-backend	Python FastAPI + PostgreSQL	服务端
Flutter 客户端	Project-S-Flutter	Flutter 3.x + Dart	Android / iOS / Web
Qt 桌面客户端	Project-S-QT	C++ Qt 6 + QML	Windows / macOS / Linux

三个客户端共享同一套后端 API，通过 WebSocket 实现多设备实时事件同步。

功能特性

• JWT 认证：登录/注册/Token 刷新，支持 Admin 用户
• AI 角色管理：创建专属 AI 角色，仅限所有者访问
• 多轮对话：支持上下文记忆，SSE 流式输出
• 记忆系统：短期/中期/长期记忆，语义搜索
• 文件上传：支持图片、视频、音频（multipart/form-data）
• 通话信令：WebSocket 信令转发（offer/answer/ice_candidate）
• 服务端推送：WebSocket 统一网关
• 扩展模块：客户端可直接调用后端扩展技能（如视频理解）
• Alembic 迁移：版本化数据库 Schema 管理
• Docker 部署：一键 docker-compose 启动

快速开始

0. 下载模型（首次必须）

项目依赖多个预训练模型，首次使用前需下载：

# 自动检测可用源（优先 modelscope.cn → huggingface.co → hf-mirror.com）
python download_models.py

# 使用魔搭社区
python download_models.py --modelscope

# 使用 hf-mirror.com
python download_model.py --mirror

# 跳过指定模块
python download_model.py --skip-embedding    # 不下载 Embedding 模型
python download_model.py --skip-whisper      # 不下载 Whisper 模型

下载内容：

• Embedding 模型：sentence-transformers/all-MiniLM-L6-v2（记忆语义搜索）
• whisper 模型

如无法下载 Embedding 模型，可在 config.yaml 中设置 embedding.default_provider: api 跳过本地模型。

Docker 部署（推荐）

# 1. 克隆仓库
git clone https:

# 2. 进入项目目录
cd Project-S-backend

# 3. 下载模型（首次）
python download_models.py --mirror

# 3. 启动所有服务
docker-compose up -d

# 4. 查看日志
docker-compose logs -f app

# 5. 健康检查
curl -k https://localhost:8000/health

本地开发

# 1. 安装依赖
pip install -r requirements.txt

# 2. 复制配置文件
cp src/configs/config.yaml.example src/configs/config.yaml

# 3. 下载模型（首次）
python download_models.py

# 4. 初始化数据库
alembic -c src/configs/alembic.ini upgrade head

# 5. 启动服务
uvicorn controllers.main:app --reload

API 文档

记得生产环境在nginx中排除一下docs的访问昂

启动后访问：

• Swagger UI: https://localhost:8000/docs
• ReDoc: https://localhost:8000/redoc

本地自签名证书会导致浏览器提示不安全，点击"继续前往"即可。生产环境请替换为真实证书。

主要端点

模块	端点	说明
Auth	POST /auth/register	用户注册
Auth	POST /auth/login	登录获取 Token
Auth	POST /auth/refresh	刷新 access_token
Auth	POST /auth/logout	退出登录
User	GET /users/me	获取当前用户信息
AIUser	GET /aiusers	获取自己的 AI 角色列表
AIUser	POST /aiusers	创建 AI 角色
Chat	POST /chat	发送消息
Chat	GET /stream	SSE 流式输出
Chat	GET /conversations	获取会话列表
Memory	GET /memories	获取记忆时间线
Memory	GET /memories/search	语义搜索记忆
Upload	POST /upload	上传文件
Upload	GET /upload/{filename}	下载文件
WebSocket	WS /ws/connect	统一推送网关（通知/AI 主动消息）
Call	WS /ws/call/{conversation_id}	通话信令 WebSocket
Expansion	GET /expansion	列出可用扩展函数
Expansion	GET /expansion/modules	列出扩展插件（含描述+函数）
Expansion	POST /expansion/invoke	直接调用扩展函数

更多接口查看API 文档

认证方式

所有受保护端点需在 Header 中携带：

Authorization: Bearer <access_token>

WebSocket 采用 连接后鉴权：连接建立后发送第一条消息完成鉴权，避免 token 暴露在 URL 中。

ws.send(JSON.stringify({
  type: 'auth',
  token: '<jwt>'
}));

配置

配置文件：src/configs/config.yaml

app:
  database_url: sqlite:///app.db    # 或 postgresql://...
  server:
    host: "0.0.0.0"
    port: 8000
  auth:
    secret_key: "change-me"
    token_expire_hours: 168
    admin_usernames: ["admin"]

Docker 环境下可通过 DATABASE_URL 环境变量覆盖数据库连接。

数据库迁移

# 生成迁移脚本
alembic -c src/configs/alembic.ini revision --autogenerate -m "描述"

# 执行迁移
alembic -c src/configs/alembic.ini upgrade head

# 回滚一级
alembic -c src/configs/alembic.ini downgrade -1

技术栈

• Python 3.11
• FastAPI + uvicorn
• SQLAlchemy 2.0 + Alembic
• PyJWT
• PostgreSQL / SQLite
• Docker + docker-compose

CLAUDE开发

遵循CLAUDE.md