# digital-human

**Repository Path**: digital-human-3/digital-human

## Basic Information

- **Project Name**: digital-human
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: develop
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-09-07
- **Last Updated**: 2026-09-19

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# AI 数字人智能咨询助手（digital-human）

> 基于大语言模型（LLM）的**对话式数字人咨询助手**：以知识库为事实源，提供口语化多轮问答、RAG 检索增强、双记忆（短期 + 长期）、多模型一键切换、SSE 流式输出，并扩展文本聊天 UI 与语音多模态（TTS/ASR）能力。
>
> 仓库为**前后端分离的单仓库（monorepo）**：后端 `fastapi-agent`（单 FastAPI 应用，以 LangChain 为核心框架），前端 `ui-agent`（React + Ant Design X 聊天界面），规划与设计文档统一存放于 `docs/`。

---

## 一、项目简介

后端以 **LangChain 1.x** 作为编排、记忆、Agent 与工具的统一底座，对外仅暴露一个 FastAPI HTTP 面（REST + SSE）；前端基于 **React 19 + Ant Design X** 构建流式聊天界面。

设计目标（详见 `docs/PRD.md`）：

- **主链路可演示**：文本问答 + RAG + 双记忆 + 流式 + 聊天 UI。
- **实训约束可兑现**：核心框架为 LangChain（编排链 / 记忆 / Agent / 工具均围绕它）、RAG 全链路且向量库使用 Chroma、≥2 模型一键切换、LangServe 作副路径、SSE 流式、配置外部化。
- **生产可上云**：单应用进程为主、关系型 DB 默认嵌入式 SQLite（可选 PostgreSQL）、外部中间件地址与密钥全部走环境变量、具备 `/health` 与 `/ready` 探针。

> 关于「数字人」形态：当前版本已实现**文本对话 + 语音播报 / 语音输入**的多模态交互；3D 虚拟形象（React Three Fiber / 口型同步）属于规划中的扩展项（`docs/` 中列为按需，未纳入当前交付），不在本仓库代码中。

---

## 二、核心功能特性

| 类别 | 功能 | 说明 |
| --- | --- | --- |
| 对话核心 | 自然语言多轮问答 | `POST /api/chat`，SSE 逐片流式返回，前端打字机渲染 |
| | RAG 检索增强 | 知识库经 Chroma 向量化检索（默认 `top_k=3`），拼入上下文；无资料时显式声明「资料不足」，不编造 |
| | 双记忆 | 短期：`ConversationBufferWindowMemory`（按 `session_id` 窗口）；长期：`VectorStoreRetrieverMemory` 挂 Chroma（按 `user_id` 分区，跨会话生效） |
| 模型 | ≥2 模型一键切换 | 云端（DeepSeek 等）+ 本地（Ollama 等）抽象；用户可在 UI 管理自有模型（BYOK，密钥加密落库） |
| 知识库 | 多格式入库与维护 | 支持 Markdown / PDF / TXT（及 Web 文本）；`/ingest`、`/retrieve`、`/refresh`、`/documents/{id}` 全流程 |
| 多用户 | 账号与隔离 | 注册 / 登录 / 刷新 / 登出（BCrypt + JWT，access 900s / refresh 7d 轮换）；`user_id` 作为会话、配置、反馈的隔离键 |
| 工具调用 | Agent 工具循环 | LangChain `@tool` + `create_agent`/`bind_tools`；模型自主决定调工具 → 执行 → 回填 → 续答（内置 `get_current_time`） |
| 工具扩展 | 多源能力 | 联网搜索、邮件发送、日历、OCR、图片理解、文生图（DashScope）、报告导出（docx / pdf）等，以注册工具方式接入 |
| 语音 | TTS / ASR（可选模块） | 语音播报（默认 Edge-TTS）、语音输入（faster-whisper，可选本地引擎） |
| 可观测 | 链路追踪（可选） | LangSmith 追踪开关可控，默认关闭时无外发流量 |
| 部署 | 容器化 | 提供 `Dockerfile`（Python 3.11-slim + uv 锁版本构建），`/health`、`/ready` 探针 |

---

## 三、技术栈说明

### 后端 `fastapi-agent`

| 层 | 技术 | 版本 / 说明 |
| --- | --- | --- |
| 语言 | Python | ≥ 3.11（锁定 3.11，偏离原始文档的 3.8，因新版 LangChain 要求） |
| Web 框架 | FastAPI + Uvicorn | ≥ 0.115 / ≥ 0.32，SSE 流式 |
| 编排核心 | **LangChain 1.x** | `langchain` / `langchain-core` / `langchain-openai` / `langchain-classic`（旧记忆类兼容包）/ `langchain-text-splitters` |
| 副路径 | LangServe | `langserve[server]`（最小问答 Runnable + Playground，可关闭） |
| 追踪 | LangSmith | `langsmith` ≥ 0.12.2（可选开启） |
| 向量库 | Chroma | ≥ 0.5，知识检索与长期记忆共用持久目录 |
| 关系型 DB | SQLAlchemy + SQLite / PostgreSQL | 默认嵌入式 SQLite；上云多副本切 PostgreSQL（连接串切换，Alembic 管迁移） |
| 缓存 | Redis | ≥ 5，**可选**；单应用下可不开 |
| 鉴权 | PyJWT + bcrypt | HS256 JWT，BCrypt 密码哈希（cost ≥ 12） |
| 数据 / 检索 | pypdf · Pillow · cryptography | 文档解析 / 图片预处理 / 加密 |
| 语音 | edge-tts · （faster-whisper 可选） | TTS 默认 Edge-TTS；ASR 本地引擎需自行安装 |
| 工具扩展 | python-docx · openpyxl · reportlab · aiosmtplib | 报告导出 / 文件解析 / PDF 生成 / 异步邮件 |
| 工程 | uv · ruff · pytest · Alembic | 依赖与虚拟环境管理、Lint、测试、DB 迁移 |

### 前端 `ui-agent`

| 层 | 技术 | 版本 / 说明 |
| --- | --- | --- |
| 框架 | React + TypeScript | React 19.2 / TypeScript ~6.0 |
| 构建 | Vite | ^8.2（rolldown 内核），开发态代理后端接口到 `:8000` |
| UI 组件 | Ant Design（antd） | ^6.6 |
| 对话组件 | Ant Design X | `@ant-design/x` ^2.9、`@ant-design/x-sdk` ^2.9、`@ant-design/x-markdown` ^2.9（Bubble / Sender / Conversations / Attachments 等） |
| 样式 | antd-style | ^4.1（`createStyles` 主题化） |
| 工具 | dayjs · @ant-design/icons | 时间处理 / 图标 |
| 质量 | ESLint 10 · typescript-eslint · React Compiler | 开发期类型与规范检查 |

---

## 四、环境要求

- **后端**：Python ≥ 3.11、[`uv`](https://docs.astral.sh/uv/)（推荐，用于依赖与虚拟环境管理）；可选 Redis、PostgreSQL（仅上云多副本时需要）。
- **前端**：Node.js ≥ 18（建议 20+），包管理器 npm / pnpm / yarn 均可。
- **外部服务（按需配置密钥）**：至少一个可用的 LLM 供应商（如 DeepSeek / Ollama 本地）、一个 Embedding 服务（默认智谱 `embedding-3`）、可选 DashScope（视觉 / 文生图）、可选搜索 / 邮件 / 地图 API。

---

## 五、安装与运行步骤

> 两个服务需分别启动：先启动后端（默认 `:8000`），再启动前端（默认 `:5173`，已配置反向代理到后端）。

### 1. 后端 `fastapi-agent`

```bash
cd fastapi-agent

# 1) 准备环境变量（复制样例，按需填写 API Key 等密钥）
cp .env.example .env

# 2) 安装依赖（uv 自动创建并同步 .venv）
uv sync

# 3) 执行数据库迁移（schema 由 Alembic 管理，不在应用启动时自动跑）
uv run alembic upgrade head

# 4) 启动服务（开发热重载）
uv run uvicorn app.main:app --reload --port 8000
# 或使用内置一键启动脚本（统一控制台日志、UTF-8 友好）
uv run python scripts/dev_run.py 8000
```

启动后：

- API 文档：`http://127.0.0.1:8000/docs`
- 存活探针：`GET /health` → `{"status":"ok",...}`
- 就绪探针：`GET /ready`（依赖 Chroma / 可选 DB 未就绪时返回 503）

### 2. 前端 `ui-agent`

```bash
cd ui-agent

# 安装依赖
npm install        # 或 pnpm install / yarn

# 启动开发服务器（默认 http://127.0.0.1:5173）
npm run dev

# 生产构建
npm run build      # tsc -b && vite build，产物在 dist/
npm run preview    # 本地预览构建产物
```

> 前端开发态通过 `vite.config.ts` 的 `server.proxy` 将 `/api`、`/models`、`/sessions`、`/ingest`、`/retrieve`、`/tts`、`/asr`、`/data`、`/langserve` 等路径代理到 `http://127.0.0.1:8000`，因此浏览器直接访问 `:5173` 即可联调。

---

## 六、目录结构说明

```
digital-human/
├── fastapi-agent/                # 后端：单 FastAPI 应用（LangChain 核心）
│   ├── app/
│   │   ├── main.py               # 应用装配：DB/Chroma + 各模块路由 + /health /ready + 静态挂载
│   │   ├── config.py             # 全量配置（Settings，配置外部化，无服务间 *_URL）
│   │   ├── common/               # 公共能力：错误码、SSE、探针、嵌入、DB 模型/会话、鉴权、rerank、追踪
│   │   └── modules/
│   │       ├── auth/             # 账号鉴权（register/login/refresh/logout/me）
│   │       ├── gateway/          # 接入层：/api/chat(SSE)、/sessions、/config/model、用户自有模型(BYOK)
│   │       ├── chat/             # 编排引擎：engine + agent(@tool/create_agent) + prompts + 内置工具
│   │       ├── knowledge/        # RAG：入库/检索/刷新/删除（Chroma 索引）
│   │       ├── memory/           # 记忆：短期窗口 + 长期向量记忆 + /save /clear
│   │       ├── model_router/     # 模型路由：ChatOpenAI 薄封装 + /models + 用户自有模型
│   │       ├── tools/            # 工具扩展：注册表 + 搜索/邮件/日历/OCR/视觉/文生图/报告
│   │       ├── voice/            # 语音：/tts /asr（可选模块）
│   │       ├── files/            # 多模态附件上传 /api/files
│   │       └── langserve_sidecar/# LangServe 副路径挂载（可关闭）
│   ├── alembic/                  # 数据库迁移脚本
│   ├── scripts/dev_run.py        # 一键启动脚本（开发态）
│   ├── tests/                    # pytest 测试套件
│   ├── pyproject.toml            # 依赖与工具配置（uv）
│   ├── .env.example              # 全量环境变量样例
│   └── Dockerfile                # 容器化镜像
│
├── ui-agent/                     # 前端：React + Ant Design X 聊天界面
│   ├── src/
│   │   ├── main.tsx / App.tsx    # 入口与根组件（XProvider + 鉴权态 + 路由切换）
│   │   ├── api.ts                # API 客户端（鉴权续签、SSE、下载、错误归一）
│   │   ├── auth/                 # 登录 / 注册界面
│   │   ├── chat/                 # 聊天主界面（Independent）、流式 Markdown、上下文
│   │   ├── model/                # 模型管理（预设、用户自有模型、选择器）
│   │   ├── mail/                 # 邮箱 SMTP 配置与邮件撰写
│   │   └── assets/               # 静态资源
│   ├── index.html / vite.config.ts / tsconfig*.json
│   └── package.json
│
├── docs/                         # 规划与设计文档（唯一事实来源 / 全局契约）
│   ├── 需求分析.md / 功能规格.md / 架构设计.md / 接口设计.md
│   ├── PRD.md                    # 整合执行视图
│   ├── 后端开发指南.md / 前端组件API.md / 接口说明.md
│   ├── 登录模块开发指南.md / 工具能力扩展开发指南.md
│   ├── AI协作指南.md / PyCharm启动指南.md / 开发排期.md
│   └── LangServe副路径改造方案.md / LangSmith接入改造清单.md
│
├── data/                         # 运行时数据（SQLite / Chroma，gitignore）
└── prototype.html                # 早期交互原型
```

---

## 七、使用示例

### 7.1 账号与鉴权

```bash
# 注册
curl -X POST http://127.0.0.1:8000/api/auth/register \
  -H 'Content-Type: application/json' \
  -d '{"username":"alice","password":"secret123"}'

# 登录，获取 access_token / refresh_token
curl -X POST http://127.0.0.1:8000/api/auth/login \
  -H 'Content-Type: application/json' \
  -d '{"username":"alice","password":"secret123"}'
```

### 7.2 对话（SSE 流式）

```bash
curl -N -X POST http://127.0.0.1:8000/api/chat \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer <ACCESS_TOKEN>' \
  -d '{
        "session_id": "demo-session",
        "message": "请用三句话介绍 RAG 的工作原理",
        "use_rag": true,
        "use_memory": true
      }'
# 响应：逐行 data: {"delta":"..."} ... 以 data: [DONE] 结束
```

### 7.3 知识库入库与检索

```bash
# 入库（JSON 文本形态）
curl -X POST http://127.0.0.1:8000/ingest \
  -H 'Content-Type: application/json' \
  -d '{"text":"数字人是…","source":"intro.md","type":"markdown"}'
# → {"doc_id":"...","chunks_count":N,"indexed":true}

# 检索
curl -X POST http://127.0.0.1:8000/retrieve \
  -H 'Content-Type: application/json' \
  -d '{"query":"什么是数字人","top_k":3}'
```

### 7.4 工具调用

```bash
# 让模型自主调用内置工具 get_current_time
curl -N -X POST http://127.0.0.1:8000/api/chat \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer <ACCESS_TOKEN>' \
  -d '{"session_id":"t1","message":"现在几点了？","tools":["get_current_time"]}'
```

### 7.5 前端界面

1. 浏览器打开 `http://127.0.0.1:5173`，注册 / 登录账号。
2. 左侧**会话侧栏**新建、切换、重命名、删除会话；右上角可**管理模型**（添加自有模型 / 切换默认模型）。
3. 在输入框提问，回答以**流式 Markdown** 逐字呈现；支持**附件上传**（先入库再随消息走 RAG）、**复制 / 重试 / 语音播报**、**点赞点踩（记忆反馈）**。
4. 顶部工具区可进入**知识库管理**（上传文档、刷新、删除）、**邮箱配置与发信**、**日历**、**OCR / 图片理解 / 文生图**、**报告导出（docx / pdf）** 等扩展能力。

---

## 八、配置说明（环境变量）

所有外部中间件地址与密钥均通过环境变量注入（配置外部化、环境隔离），**不进代码或镜像**。完整样例见 `fastapi-agent/.env.example`，关键项：

- `AUTH_ENABLED`：是否强制 JWT 鉴权（`false` 为演示态，回退 `default-user`）。
- `JWT_SECRET`：≥32 字符，生产必须配置，缺失则启动失败（fail-fast）。
- `DATABASE_URL`：默认 `sqlite:///./data/dev.sqlite3`；生产可切 PostgreSQL。
- `CHROMA_PERSIST_DIR`：Chroma 持久目录（知识 + 长期记忆共用）。
- `DEEPSEEK_*` / `OLLAMA_*`：模型供应商账号（**系统默认模型已于 2026-09-12 下线，对话模型走纯 BYOK**：用户经 `/api/user-models` 自带 API Key（密钥加密落库），服务端 `DEEPSEEK_API_KEY` 不再被 `ModelRouter` 消费，仅为历史遗留字段；本地 Ollama 同理由用户自配）。
- `EMBEDDING_*`：嵌入服务（默认智谱 `embedding-3`）。
- `DASHSCOPE_*`：视觉 / OCR / 文生图（阿里云百炼）。
- `SEARCH_*` / `GAODE_API_KEY` / `WEATHER_API_KEY`：工具扩展所需外部 API。
- `LANGSMITH_*`：链路追踪（默认关闭）。
- `LANGSERVE_ENABLED`：LangServe 副路径（默认关闭）。

---

## 九、部署

后端提供容器化方案（`fastapi-agent/Dockerfile`，基于 `python:3.11-slim` + `uv` 锁版本构建）：

```bash
cd fastapi-agent
docker build -t digital-human-api .
docker run -p 8000:8000 --env-file .env digital-human-api
```

生产化要点（详见 `docs/架构设计.md` §3.5）：DB 迁移经 Alembic 由 CI/CD 或一次性 Job 执行（不在应用启动自动跑）；多副本时需共享 Chroma 并将嵌入式 DB 切换为集中式 PostgreSQL；密钥走环境变量 / Secret，不进镜像。

---

## 十、测试与质量

```bash
# 后端：运行测试与 Lint
cd fastapi-agent
uv run pytest
uv run ruff check app tests

# 前端：类型检查与 Lint
cd ui-agent
npm run build      # 含 tsc -b 类型检查
npm run lint
```

---

## 十一、文档与参考

规划与设计以 `docs/` 为**唯一事实来源 / 全局契约**：

- 需求与功能：`需求分析.md`、`功能规格.md`、`PRD.md`
- 架构与接口：`架构设计.md`、`接口设计.md`、`接口说明.md`
- 实施指南：`后端开发指南.md`、`前端组件API.md`、`登录模块开发指南.md`、`工具能力扩展开发指南.md`、`LangServe副路径改造方案.md`、`LangSmith接入改造清单.md`
- 协作与排期：`AI协作指南.md`、`开发排期.md`、`PyCharm启动指南.md`

---

## 许可证

许可证以仓库实际配置为准。