docs: add digital employee platform design document
Multi-tenant platform design with unified LLM provider abstraction, RAG knowledge base, and tenant-isolated data storage. MVP uses SQLite + ChromaDB, with planned migration to PostgreSQL + pgvector. Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
This commit is contained in:
root
parent
147104819b
commit
5c13f08c03
597
docs/plans/2026-05-05-digital-employee-design.md
Normal file
597
docs/plans/2026-05-05-digital-employee-design.md
Normal file
@ -0,0 +1,597 @@
|
||||
# 数字员工平台设计文档
|
||||
|
||||
> 日期：2026-05-05
|
||||
> 状态：已批准
|
||||
|
||||
## 1. 背景与目标
|
||||
|
||||
### 1.1 背景
|
||||
|
||||
企业对 AI 数字员工的需求日益增长，但不同企业的业务场景、知识体系、合规要求各不相同。现有解决方案要么是通用聊天机器人（缺乏企业定制），要么是单点 SaaS 产品（数据隔离弱、模型选择受限）。需要一个多租户平台，让每家企业能配置专属数字员工，接入自选 LLM，使用私有知识库。
|
||||
|
||||
### 1.2 目标
|
||||
|
||||
- 构建多租户数字员工平台，支持企业级数据隔离与独立计费
|
||||
- 统一 LLM Provider 抽象层，企业可自选模型提供商（OpenAI / 通义千问 / 可扩展）
|
||||
- RAG 知识库支持企业私有文档上传与检索增强生成
|
||||
- 提供管理后台与对话前端，形成完整可演示链路
|
||||
|
||||
### 1.3 成功标准
|
||||
|
||||
| 指标 | MVP 目标 |
|
||||
|------|----------|
|
||||
| 租户隔离 | 企业间数据零泄露，API Key 独立计费 |
|
||||
| 对话延迟 | 首 token 响应 < 3s（不含 LLM 调用开销） |
|
||||
| RAG 准确性 | 知识库内问题 Top-3 召回率 > 80% |
|
||||
| 可演示性 | 管理后台 + 对话界面端到端可用 |
|
||||
| Provider 扩展 | 新增 Provider 实现工作量 < 1 天 |
|
||||
|
||||
## 2. 范围
|
||||
|
||||
### 2.1 MVP 范围（P0）
|
||||
|
||||
1. 企业租户管理（CRUD + API Key 配置）
|
||||
2. 数字员工人设配置（角色、语气、专业知识描述）
|
||||
3. 对话接口（实时聊天，SSE 流式响应）
|
||||
4. RAG 知识库（上传文档 → 分块嵌入 → 检索增强生成）
|
||||
5. 对话历史存储与查询
|
||||
|
||||
### 2.2 MVP 基础版（P1）
|
||||
|
||||
6. 管理后台 UI（企业管理、员工配置、对话监控）
|
||||
7. 对话前端 UI（聊天界面）
|
||||
|
||||
### 2.3 后续迭代（P2）
|
||||
|
||||
8. 用量统计 / 计费
|
||||
9. 权限控制（企业管理员 vs 普通用户）
|
||||
|
||||
### 2.4 拓展功能（P3，按价值排序）
|
||||
|
||||
1. **对话质量评估**：自动评估 RAG 回答的准确性与相关性
|
||||
2. **数字员工模板市场**：预置客服/HR/销售等角色模板，一键启用
|
||||
3. **多渠道接入**：微信/钉钉/飞书/Web 统一对话接口
|
||||
4. **审批工作流**：敏感操作前需人类确认
|
||||
5. **审计日志与合规**：完整对话审计链路
|
||||
|
||||
### 2.5 非目标
|
||||
|
||||
- 自训练/微调模型
|
||||
- 实时语音对话
|
||||
- 多模态输入（图片/视频）
|
||||
- 移动端原生 App
|
||||
|
||||
## 3. 方案对比
|
||||
|
||||
### 3.1 方案 A：轻量直连架构
|
||||
|
||||
```
|
||||
FastAPI → Provider 抽象层 → OpenAI/通义千问 API
|
||||
→ SQLite + ChromaDB（嵌入式向量库）
|
||||
→ 文件存储（对话历史）
|
||||
```
|
||||
|
||||
- 零外部依赖，`pip install` 即跑
|
||||
- 开发周期 1-2 周
|
||||
- 单机部署，不适合大规模
|
||||
|
||||
### 3.2 方案 B：LangChain 编排架构
|
||||
|
||||
```
|
||||
FastAPI → LangChain/LangGraph → 多 LLM Provider
|
||||
→ PostgreSQL + pgvector
|
||||
→ Redis（缓存/会话）
|
||||
```
|
||||
|
||||
- LangChain 500+ 集成，LangGraph 支持多步 Agent
|
||||
- 重依赖，升级频繁有 breaking change
|
||||
- 生产维护成本高
|
||||
|
||||
### 3.3 方案 C：自研编排 + PostgreSQL 全栈
|
||||
|
||||
```
|
||||
FastAPI → 自研 Provider 抽象 + RAG Pipeline
|
||||
→ PostgreSQL + pgvector（统一存储）
|
||||
→ Redis（会话/缓存）
|
||||
```
|
||||
|
||||
- 完全可控，无重框架依赖
|
||||
- PostgreSQL 统一关系数据 + 向量检索
|
||||
- RAG pipeline 需自建，初始工作量较大
|
||||
|
||||
### 3.4 决策：方案 A 先行，演进到方案 C
|
||||
|
||||
| 阶段 | 存储 | 向量库 | 缓存 | 理由 |
|
||||
|------|------|--------|------|------|
|
||||
| MVP | SQLite | ChromaDB | 无 | 零外部依赖，快速验证 |
|
||||
| V1 | PostgreSQL | pgvector | Redis | 生产级，统一存储 |
|
||||
|
||||
## 4. 推荐方案详细设计
|
||||
|
||||
### 4.1 系统架构总览
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────┐
|
||||
│ 前端层 (TypeScript) │
|
||||
│ ┌──────────────┐ ┌──────────────┐ ┌───────────────┐ │
|
||||
│ │ 管理后台 UI │ │ 对话前端 UI │ │ 模板市场 UI │ │
|
||||
│ └──────┬───────┘ └──────┬───────┘ └───────┬───────┘ │
|
||||
└─────────┼─────────────────┼──────────────────┼──────────┘
|
||||
│ │ │
|
||||
▼ ▼ ▼
|
||||
┌─────────────────────────────────────────────────────────┐
|
||||
│ API 网关层 (FastAPI) │
|
||||
│ ┌──────────┐ ┌───────────┐ ┌──────────┐ ┌───────────┐ │
|
||||
│ │ 租户管理 │ │ 员工配置 │ │ 对话接口 │ │ 知识库管理 │ │
|
||||
│ └──────────┘ └───────────┘ └──────────┘ └───────────┘ │
|
||||
└─────────────────────┬───────────────────────────────────┘
|
||||
│
|
||||
┌───────────┴───────────┐
|
||||
▼ ▼
|
||||
┌──────────────────┐ ┌─────────────────────┐
|
||||
│ 对话编排层 │ │ RAG Pipeline │
|
||||
│ ┌─────────────┐ │ │ ┌─────────────────┐ │
|
||||
│ │ 会话管理 │ │ │ │ 文档解析/分块 │ │
|
||||
│ │ Prompt 构建 │ │ │ │ 嵌入生成 │ │
|
||||
│ │ 流式响应 │ │ │ │ 向量检索 │ │
|
||||
│ └─────────────┘ │ │ │ 上下文注入 │ │
|
||||
│ ┌─────────────┐ │ │ └─────────────────┘ │
|
||||
│ │ Provider │ │ └─────────────────────┘
|
||||
│ │ 抽象层 │ │
|
||||
│ │ ┌────────┐ │ │
|
||||
│ │ │ OpenAI │ │ │
|
||||
│ │ │ 通义 │ │ │
|
||||
│ │ │ ... │ │ │
|
||||
│ │ └────────┘ │ │
|
||||
│ └─────────────┘ │
|
||||
└──────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────┐
|
||||
│ 存储层 │
|
||||
│ MVP: SQLite + ChromaDB + 文件存储 │
|
||||
│ V1: PostgreSQL + pgvector + Redis │
|
||||
└─────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
### 4.2 核心模块设计
|
||||
|
||||
#### 4.2.1 租户管理模块
|
||||
|
||||
**数据模型：**
|
||||
|
||||
```python
|
||||
class Tenant:
|
||||
id: UUID # 租户 ID
|
||||
name: str # 企业名称
|
||||
slug: str # URL 标识（唯一）
|
||||
status: TenantStatus # active / suspended / deleted
|
||||
created_at: datetime
|
||||
updated_at: datetime
|
||||
|
||||
class TenantConfig:
|
||||
id: UUID
|
||||
tenant_id: UUID # 关联租户
|
||||
llm_provider: str # openai / qwen / anthropic
|
||||
llm_api_key: str # 加密存储的 API Key
|
||||
llm_model: str # gpt-4o / qwen-max / ...
|
||||
llm_base_url: str | None # 自定义 API 端点（可选）
|
||||
max_tokens_per_month: int # 用量限制
|
||||
created_at: datetime
|
||||
updated_at: datetime
|
||||
```
|
||||
|
||||
**API 端点：**
|
||||
|
||||
| 方法 | 路径 | 说明 |
|
||||
|------|------|------|
|
||||
| POST | `/api/v1/tenants` | 创建租户 |
|
||||
| GET | `/api/v1/tenants/{id}` | 获取租户详情 |
|
||||
| PUT | `/api/v1/tenants/{id}` | 更新租户 |
|
||||
| DELETE | `/api/v1/tenants/{id}` | 删除租户（软删除） |
|
||||
| PUT | `/api/v1/tenants/{id}/config` | 更新 LLM 配置 |
|
||||
|
||||
**安全约束：**
|
||||
- API Key 使用 AES-256 加密存储，密钥从环境变量读取
|
||||
- 租户间数据严格隔离，所有查询强制带 `tenant_id` 过滤
|
||||
- 软删除策略，删除后 30 天可恢复
|
||||
|
||||
#### 4.2.2 数字员工配置模块
|
||||
|
||||
**数据模型：**
|
||||
|
||||
```python
|
||||
class DigitalEmployee:
|
||||
id: UUID
|
||||
tenant_id: UUID # 所属租户
|
||||
name: str # 员工名称（如"客服小助手"）
|
||||
role: str # 角色：customer_service / hr / sales / ...
|
||||
avatar_url: str | None # 头像
|
||||
system_prompt: str # 人设系统提示词
|
||||
greeting: str | None # 开场白
|
||||
temperature: float # 生成温度 0.0-1.0
|
||||
max_context_messages: int # 上下文窗口消息数
|
||||
knowledge_base_ids: list[UUID] # 关联知识库
|
||||
status: EmployeeStatus # active / inactive
|
||||
created_at: datetime
|
||||
updated_at: datetime
|
||||
```
|
||||
|
||||
**API 端点：**
|
||||
|
||||
| 方法 | 路径 | 说明 |
|
||||
|------|------|------|
|
||||
| POST | `/api/v1/tenants/{tid}/employees` | 创建数字员工 |
|
||||
| GET | `/api/v1/tenants/{tid}/employees` | 列出数字员工 |
|
||||
| GET | `/api/v1/tenants/{tid}/employees/{eid}` | 获取详情 |
|
||||
| PUT | `/api/v1/tenants/{tid}/employees/{eid}` | 更新配置 |
|
||||
| DELETE | `/api/v1/tenants/{tid}/employees/{eid}` | 删除 |
|
||||
|
||||
#### 4.2.3 对话接口模块
|
||||
|
||||
**对话流程：**
|
||||
|
||||
```
|
||||
用户消息
|
||||
→ 会话加载（历史上下文）
|
||||
→ RAG 检索（如果员工关联了知识库）
|
||||
→ 查询向量化
|
||||
→ ChromaDB/pgvector 相似度检索 Top-K
|
||||
→ 上下文注入到 Prompt
|
||||
→ Prompt 构建（system + 知识上下文 + 历史消息 + 用户消息）
|
||||
→ LLM Provider 调用（流式）
|
||||
→ SSE 流式响应
|
||||
→ 持久化对话记录
|
||||
```
|
||||
|
||||
**数据模型：**
|
||||
|
||||
```python
|
||||
class Conversation:
|
||||
id: UUID
|
||||
tenant_id: UUID
|
||||
employee_id: UUID
|
||||
user_id: str # 外部用户标识
|
||||
title: str | None
|
||||
created_at: datetime
|
||||
updated_at: datetime
|
||||
|
||||
class Message:
|
||||
id: UUID
|
||||
conversation_id: UUID
|
||||
role: MessageRole # user / assistant / system
|
||||
content: str
|
||||
token_count: int | None
|
||||
sources: list[dict] | None # RAG 引用来源
|
||||
created_at: datetime
|
||||
```
|
||||
|
||||
**API 端点：**
|
||||
|
||||
| 方法 | 路径 | 说明 |
|
||||
|------|------|------|
|
||||
| POST | `/api/v1/tenants/{tid}/employees/{eid}/conversations` | 创建对话 |
|
||||
| GET | `/api/v1/tenants/{tid}/conversations` | 列出对话 |
|
||||
| GET | `/api/v1/tenants/{tid}/conversations/{cid}` | 获取对话详情（含消息） |
|
||||
| POST | `/api/v1/tenants/{tid}/conversations/{cid}/messages` | 发送消息（SSE 流式响应） |
|
||||
| DELETE | `/api/v1/tenants/{tid}/conversations/{cid}` | 删除对话 |
|
||||
|
||||
**SSE 响应格式：**
|
||||
|
||||
```
|
||||
event: message_start
|
||||
data: {"conversation_id": "...", "message_id": "..."}
|
||||
|
||||
event: token
|
||||
data: {"content": "你"}
|
||||
|
||||
event: token
|
||||
data: {"content": "好"}
|
||||
|
||||
event: sources
|
||||
data: {"documents": [{"title": "...", "snippet": "...", "score": 0.92}]}
|
||||
|
||||
event: message_end
|
||||
data: {"token_count": 156}
|
||||
|
||||
event: error
|
||||
data: {"code": "provider_error", "message": "..."}
|
||||
```
|
||||
|
||||
#### 4.2.4 RAG 知识库模块
|
||||
|
||||
**处理流程：**
|
||||
|
||||
```
|
||||
文档上传
|
||||
→ 文件类型检测（PDF / DOCX / TXT / MD）
|
||||
→ 文档解析（提取纯文本）
|
||||
→ 文本分块（RecursiveCharacterTextSplitter）
|
||||
→ chunk_size: 500, overlap: 50
|
||||
→ 嵌入生成（调用 Embedding API）
|
||||
→ 向量存储（ChromaDB，按 tenant_id 隔离命名空间）
|
||||
→ 元数据存储（文档标题、来源、分块偏移量）
|
||||
```
|
||||
|
||||
**数据模型：**
|
||||
|
||||
```python
|
||||
class KnowledgeBase:
|
||||
id: UUID
|
||||
tenant_id: UUID
|
||||
name: str
|
||||
description: str | None
|
||||
embedding_model: str # text-embedding-3-small / ...
|
||||
chunk_count: int
|
||||
created_at: datetime
|
||||
updated_at: datetime
|
||||
|
||||
class Document:
|
||||
id: UUID
|
||||
knowledge_base_id: UUID
|
||||
tenant_id: UUID
|
||||
filename: str
|
||||
file_type: str # pdf / docx / txt / md
|
||||
file_size: int
|
||||
chunk_count: int
|
||||
status: DocumentStatus # processing / ready / failed
|
||||
error_message: str | None
|
||||
created_at: datetime
|
||||
```
|
||||
|
||||
**API 端点：**
|
||||
|
||||
| 方法 | 路径 | 说明 |
|
||||
|------|------|------|
|
||||
| POST | `/api/v1/tenants/{tid}/knowledge-bases` | 创建知识库 |
|
||||
| POST | `/api/v1/tenants/{tid}/knowledge-bases/{kid}/documents` | 上传文档 |
|
||||
| GET | `/api/v1/tenants/{tid}/knowledge-bases/{kid}/documents` | 列出文档 |
|
||||
| DELETE | `/api/v1/tenants/{tid}/knowledge-bases/{kid}/documents/{did}` | 删除文档 |
|
||||
| GET | `/api/v1/tenants/{tid}/knowledge-bases` | 列出知识库 |
|
||||
| DELETE | `/api/v1/tenants/{tid}/knowledge-bases/{kid}` | 删除知识库 |
|
||||
|
||||
#### 4.2.5 LLM Provider 抽象层
|
||||
|
||||
**设计原则：**
|
||||
- 统一接口，Provider 可插拔
|
||||
- 每个企业独立 API Key，按租户路由
|
||||
- 支持流式和非流式调用
|
||||
- 统一错误处理与重试
|
||||
|
||||
```python
|
||||
from abc import ABC, abstractmethod
|
||||
from dataclasses import dataclass
|
||||
|
||||
@dataclass
|
||||
class LLMMessage:
|
||||
role: str # system / user / assistant
|
||||
content: str
|
||||
|
||||
@dataclass
|
||||
class LLMResponse:
|
||||
content: str
|
||||
token_usage: dict
|
||||
model: str
|
||||
finish_reason: str
|
||||
|
||||
class BaseLLMProvider(ABC):
|
||||
"""LLM Provider 抽象基类"""
|
||||
|
||||
@abstractmethod
|
||||
async def chat(
|
||||
self,
|
||||
messages: list[LLMMessage],
|
||||
model: str,
|
||||
temperature: float = 0.7,
|
||||
max_tokens: int = 2048,
|
||||
**kwargs,
|
||||
) -> LLMResponse:
|
||||
...
|
||||
|
||||
@abstractmethod
|
||||
async def chat_stream(
|
||||
self,
|
||||
messages: list[LLMMessage],
|
||||
model: str,
|
||||
temperature: float = 0.7,
|
||||
max_tokens: int = 2048,
|
||||
**kwargs,
|
||||
) -> AsyncIterator[str]:
|
||||
...
|
||||
|
||||
@abstractmethod
|
||||
async def embed(self, texts: list[str], model: str) -> list[list[float]]:
|
||||
...
|
||||
|
||||
class OpenAIProvider(BaseLLMProvider):
|
||||
"""OpenAI / 兼容 OpenAI 接口的 Provider"""
|
||||
|
||||
class QwenProvider(BaseLLMProvider):
|
||||
"""通义千问 Provider（兼容 OpenAI 接口格式）"""
|
||||
|
||||
# Provider 注册表
|
||||
PROVIDERS: dict[str, type[BaseLLMProvider]] = {
|
||||
"openai": OpenAIProvider,
|
||||
"qwen": QwenProvider,
|
||||
}
|
||||
|
||||
def get_provider(provider_name: str, api_key: str, base_url: str | None = None) -> BaseLLMProvider:
|
||||
provider_cls = PROVIDERS.get(provider_name)
|
||||
if not provider_cls:
|
||||
raise ValueError(f"Unknown provider: {provider_name}")
|
||||
return provider_cls(api_key=api_key, base_url=base_url)
|
||||
```
|
||||
|
||||
**Provider 配置约定：**
|
||||
|
||||
| Provider | chat model | embedding model | 特殊说明 |
|
||||
|----------|-----------|----------------|---------|
|
||||
| openai | gpt-4o / gpt-4o-mini | text-embedding-3-small | 标准 OpenAI API |
|
||||
| qwen | qwen-max / qwen-plus | text-embedding-v3 | 兼容 OpenAI SDK 格式 |
|
||||
|
||||
### 4.3 安全设计
|
||||
|
||||
#### 4.3.1 数据隔离
|
||||
|
||||
- 所有数据表包含 `tenant_id` 字段
|
||||
- 所有查询强制 `WHERE tenant_id = :current_tenant`
|
||||
- API 中间件自动注入 `tenant_id`，业务代码无法绕过
|
||||
- ChromaDB 使用 tenant_id 作为 collection namespace 隔离向量数据
|
||||
|
||||
#### 4.3.2 API Key 安全
|
||||
|
||||
- LLM API Key 使用 AES-256-GCM 加密存储
|
||||
- 加密密钥从环境变量 `ENCRYPTION_KEY` 读取，不入库不入日志
|
||||
- 运行时解密仅用于发起 LLM 调用，不返回给前端
|
||||
|
||||
#### 4.3.3 输入校验
|
||||
|
||||
- 所有 API 入参使用 Pydantic 校验
|
||||
- 文档上传限制：单文件 < 20MB，仅允许 pdf/docx/txt/md
|
||||
- 对话消息长度限制：单条 < 10000 字符
|
||||
- 速率限制：每租户每分钟 60 次请求
|
||||
|
||||
### 4.4 技术栈
|
||||
|
||||
| 层 | MVP 技术选型 | V1 演进 |
|
||||
|----|------------|---------|
|
||||
| 后端框架 | FastAPI 0.115+ | FastAPI |
|
||||
| 数据库 | SQLite (aiosqlite) | PostgreSQL 16 |
|
||||
| 向量库 | ChromaDB 0.5+ | pgvector |
|
||||
| 缓存 | 无 | Redis |
|
||||
| ORM | SQLAlchemy 2.0+ (async) | SQLAlchemy 2.0+ |
|
||||
| 嵌入/LLM | openai SDK | openai SDK |
|
||||
| 文档解析 | PyPDF2 + python-docx | 同左 |
|
||||
| 前端框架 | React + TypeScript + Vite | 同左 |
|
||||
| 前端 UI | Ant Design | Ant Design |
|
||||
| 对话前端 | 自研 Chat UI 组件 | 同左 |
|
||||
|
||||
### 4.5 项目结构
|
||||
|
||||
```
|
||||
digital-employee-platform/
|
||||
├── backend/
|
||||
│ ├── app/
|
||||
│ │ ├── __init__.py
|
||||
│ │ ├── main.py # FastAPI 入口
|
||||
│ │ ├── config.py # 配置管理
|
||||
│ │ ├── database.py # 数据库连接
|
||||
│ │ ├── models/ # SQLAlchemy 模型
|
||||
│ │ │ ├── __init__.py
|
||||
│ │ │ ├── tenant.py
|
||||
│ │ │ ├── employee.py
|
||||
│ │ │ ├── conversation.py
|
||||
│ │ │ └── knowledge.py
|
||||
│ │ ├── schemas/ # Pydantic 请求/响应模型
|
||||
│ │ │ ├── __init__.py
|
||||
│ │ │ ├── tenant.py
|
||||
│ │ │ ├── employee.py
|
||||
│ │ │ ├── conversation.py
|
||||
│ │ │ └── knowledge.py
|
||||
│ │ ├── api/ # API 路由
|
||||
│ │ │ ├── __init__.py
|
||||
│ │ │ ├── v1/
|
||||
│ │ │ │ ├── __init__.py
|
||||
│ │ │ │ ├── tenants.py
|
||||
│ │ │ │ ├── employees.py
|
||||
│ │ │ │ ├── conversations.py
|
||||
│ │ │ │ └── knowledge.py
|
||||
│ │ │ └── deps.py # 依赖注入
|
||||
│ │ ├── services/ # 业务逻辑
|
||||
│ │ │ ├── __init__.py
|
||||
│ │ │ ├── tenant_service.py
|
||||
│ │ │ ├── employee_service.py
|
||||
│ │ │ ├── conversation_service.py
|
||||
│ │ │ ├── knowledge_service.py
|
||||
│ │ │ └── rag_service.py
|
||||
│ │ ├── providers/ # LLM Provider 抽象层
|
||||
│ │ │ ├── __init__.py
|
||||
│ │ │ ├── base.py
|
||||
│ │ │ ├── openai_provider.py
|
||||
│ │ │ └── qwen_provider.py
|
||||
│ │ └── middleware/ # 中间件
|
||||
│ │ ├── __init__.py
|
||||
│ │ └── tenant.py # 租户隔离中间件
|
||||
│ ├── tests/ # 测试
|
||||
│ │ ├── __init__.py
|
||||
│ │ ├── conftest.py
|
||||
│ │ ├── test_tenants.py
|
||||
│ │ ├── test_employees.py
|
||||
│ │ ├── test_conversations.py
|
||||
│ │ ├── test_knowledge.py
|
||||
│ │ └── test_providers.py
|
||||
│ ├── alembic/ # 数据库迁移
|
||||
│ │ └── ...
|
||||
│ ├── pyproject.toml
|
||||
│ └── .env.example
|
||||
├── frontend/
|
||||
│ ├── src/
|
||||
│ │ ├── api/ # API 客户端
|
||||
│ │ ├── components/ # 通用组件
|
||||
│ │ ├── pages/
|
||||
│ │ │ ├── admin/ # 管理后台页面
|
||||
│ │ │ │ ├── Tenants.tsx
|
||||
│ │ │ │ ├── Employees.tsx
|
||||
│ │ │ │ └── Knowledge.tsx
|
||||
│ │ │ └── chat/ # 对话前端页面
|
||||
│ │ │ └── Chat.tsx
|
||||
│ │ ├── App.tsx
|
||||
│ │ └── main.tsx
|
||||
│ ├── package.json
|
||||
│ ├── tsconfig.json
|
||||
│ └── vite.config.ts
|
||||
└── docs/
|
||||
└── plans/
|
||||
```
|
||||
|
||||
## 5. 错误处理
|
||||
|
||||
| 错误类型 | 处理策略 | HTTP 状态码 |
|
||||
|---------|---------|------------|
|
||||
| LLM Provider 调用失败 | 指数退避重试 2 次，记录日志，返回降级提示 | 502 |
|
||||
| LLM API Key 无效/过期 | 返回配置错误提示，不重试 | 401 |
|
||||
| 租户 API 限流 | 返回 429，附带 Retry-After 头 | 429 |
|
||||
| 文档解析失败 | 标记文档状态为 failed，记录错误信息 | 200（异步） |
|
||||
| RAG 无相关结果 | 正常返回，不注入知识上下文，LLM 按通用知识回答 | - |
|
||||
| 向量库写入失败 | 重试 1 次，失败则文档标记 failed | 200（异步） |
|
||||
| 数据库连接失败 | 返回 503，记录告警 | 503 |
|
||||
|
||||
## 6. 测试策略
|
||||
|
||||
### 6.1 单元测试
|
||||
|
||||
- Provider 抽象层：mock LLM API 响应，验证接口一致性
|
||||
- 服务层：mock 数据库，验证业务逻辑
|
||||
- RAG Pipeline：mock embedding，验证分块、检索逻辑
|
||||
|
||||
### 6.2 集成测试
|
||||
|
||||
- 端到端对话流：使用真实 LLM API（测试 Key），验证完整链路
|
||||
- 租户隔离：创建两个租户，验证数据不互渗
|
||||
- RAG 问答：上传文档后提问，验证回答包含文档内容
|
||||
|
||||
### 6.3 安全测试
|
||||
|
||||
- 越权访问：租户 A 尝试访问租户 B 资源，必须 403
|
||||
- API Key 不出现在日志和 API 响应中
|
||||
- 文档上传类型和大小限制
|
||||
|
||||
### 6.4 性能测试
|
||||
|
||||
- 对话接口：p99 < 3s（不含 LLM 调用）
|
||||
- 文档上传：10MB PDF 解析 < 30s
|
||||
- 并发：单租户 10 并发对话无异常
|
||||
|
||||
## 7. 演进路径
|
||||
|
||||
```
|
||||
MVP (方案 A) V1 (方案 C)
|
||||
───────────── ──────────────
|
||||
SQLite + ChromaDB ──迁移──→ PostgreSQL + pgvector
|
||||
文件存储对话历史 ──迁移──→ PostgreSQL JSONB
|
||||
无缓存 ──新增──→ Redis 会话缓存
|
||||
单实例部署 ──演进──→ Docker Compose 多服务
|
||||
基础对话 ──新增──→ 对话质量评估
|
||||
无模板 ──新增──→ 数字员工模板市场
|
||||
Web 对话 ──新增──→ 多渠道接入
|
||||
```
|
||||
44
memory/2026-05-05.md
Normal file
44
memory/2026-05-05.md
Normal file
@ -0,0 +1,44 @@
|
||||
# 2026-05-05
|
||||
|
||||
## 纪要
|
||||
|
||||
- 数字员工平台项目启动，完成设计文档
|
||||
|
||||
## 决策
|
||||
|
||||
### 综合型数字员工平台 - 架构决策
|
||||
|
||||
- **结论**：采用方案 A（轻量直连）先行 MVP，演进到方案 C（自研编排 + PostgreSQL 全栈）
|
||||
- **理由**：
|
||||
- MVP 用 SQLite + ChromaDB 零外部依赖，1-2 周可交付
|
||||
- 避免 LangChain 重依赖和频繁 breaking change
|
||||
- 自研 Provider 抽象层保持轻量可控
|
||||
- 生产级方案用 PostgreSQL + pgvector 统一存储
|
||||
- **影响**：
|
||||
- 项目结构按模块化设计，存储层可替换
|
||||
- Provider 抽象层接口需稳定，后续新增 Provider 不改业务代码
|
||||
|
||||
### 技术选型
|
||||
|
||||
- **后端**：Python FastAPI + SQLAlchemy 2.0 async
|
||||
- **前端**：React + TypeScript + Vite + Ant Design
|
||||
- **存储 MVP**：SQLite + ChromaDB
|
||||
- **存储 V1**：PostgreSQL + pgvector + Redis
|
||||
- **LLM MVP**：OpenAI + 通义千问（兼容 OpenAI SDK 格式）
|
||||
|
||||
### 多租户隔离策略
|
||||
|
||||
- 共享服务实例 + API Key 隔离 + 独立知识库（ChromaDB namespace 隔离）
|
||||
- 所有数据表强制 tenant_id 过滤
|
||||
- LLM API Key AES-256 加密存储
|
||||
|
||||
### MVP 范围
|
||||
|
||||
- P0：租户管理、员工配置、对话接口、RAG 知识库、对话历史
|
||||
- P1：管理后台 UI、对话前端 UI
|
||||
- P2：用量统计/计费、权限控制
|
||||
- P3：对话质量评估、模板市场、多渠道接入、审批工作流、审计日志
|
||||
|
||||
## 问题与修复
|
||||
|
||||
（暂无）
|
||||
Loading…
x
Reference in New Issue
Block a user