# AI Chat Service 设计方案 > **目标：** 在 TopFans Backend 微服务体系中，新增 AI 伴侣对话服务，实现「用户输入→人设注入→大模型调用→记忆召回→合规审核→流式输出」完整链路。 --- ## 一、架构设计 ### 1.1 整体架构 ``` ┌─────────────────────────────────────────────────────────────────────────────┐ │ Mobile App │ └─────────────────────────────────┬───────────────────────────────────────────┘ │ HTTP + JWT ▼ ┌─────────────────────────────────────────────────────────────────────────────┐ │ Gateway (:8080) │ │ ┌─────────────────────────────────────────────────────────────────────┐ │ │ │ AIChatController │ │ │ │ POST /api/v1/ai-chat/send # 发送消息（流式） │ │ │ │ GET /api/v1/ai-chat/personas # 获取人设列表 │ │ │ │ GET /api/v1/ai-chat/history/{sessionId} # 获取对话历史 │ │ │ └─────────────────────────────────────────────────────────────────────┘ │ │ │ │ │ │ Dubbo Triple (gRPC) │ └────────────────────────────────────┼─────────────────────────────────────────┘ │ ▼ ┌─────────────────────────────────────────────────────────────────────────────┐ │ AIChatService (:20008) │ │ │ │ ┌──────────────────────────────────────────────────────────────────────┐ │ │ │ Provider 层 │ │ │ │ AIChatProvider (Dubbo RPC 入口) │ │ │ └──────────────────────────────────────────────────────────────────────┘ │ │ │ │ │ ▼ │ │ ┌──────────────────────────────────────────────────────────────────────┐ │ │ │ Service 层 │ │ │ │ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ ┌────────────┐ │ │ │ │ │LLMService │ │PersonaService│ │MemoryService │ │AuditService│ │ │ │ │ │大模型调用 │ │人设管理 │ │记忆管理 │ │合规审核 │ │ │ │ │ └─────────────┘ └─────────────┘ └─────────────┘ └────────────┘ │ │ │ └──────────────────────────────────────────────────────────────────────┘ │ │ │ │ ┌──────────────────────────────────────────────────────────────────────┐ │ │ │ Repository 层 │ │ │ │ ┌───────────────────────────┐ ┌───────────────────────────────────┐ │ │ │ │ │ PostgreSQL │ │ Redis │ │ │ │ │ │ user_memories (长期记忆) │ │ context:{sessionId} - 短期上下文 │ │ │ │ │ │ user_custom_personas (人设)│ │ persona_cache:{userId}:{id} │ │ │ │ │ └───────────────────────────┘ └───────────────────────────────────┘ │ │ │ └──────────────────────────────────────────────────────────────────────┘ │ └─────────────────────────────────────────────────────────────────────────────┘ ``` ### 1.2 服务间调用关系 ``` Gateway ────────────────────────────────────────────────────────────────────── │ │ │ Dubbo Triple 协议 │ ▼ │ AIChatService │ │ │ ├─── 调用 MiniMax M2-her API ──► AI 大模型 (外部服务) │ │ │ ├─── 读写 ──► Redis (短期上下文、Session) │ │ │ └─── 读写 ──► PostgreSQL (长期记忆 + 用户自定义人设) │ ``` ### 1.3 数据流 ``` 1. 用户发送消息 Mobile → Gateway → AIChatService 2. 前置审核 AIChatService.AuditService.audit_text() → 通过/拒绝 3. 记忆召回 AIChatService.MemoryService.recall_memories() → 召回相关记忆 4. Prompt 组装 AIChatService.PersonaService.get_persona() → 获取人设 组装: SystemPrompt + 召回记忆 + 对话历史 + 用户输入 5. 大模型调用 (流式) AIChatService.LLMService.stream_chat() → MiniMax API 6. 后置审核 (逐Token) AIChatService.AuditService.audit_response() → 拦截敏感输出 7. 流式返回 Gateway → Mobile (SSE) 8. 保存上下文 AIChatService.MemoryService.save_context() → Redis 9. 触发记忆提取 (每5轮) AIChatService.MemoryService.extract_memory() → PostgreSQL ``` --- ## 二、目录结构 ``` services/aiChatService/ ├── main.go # 程序入口 ├── configs/ │ └── dubbo.yaml # Dubbo 配置 ├── go.mod ├── go.sum ├── provider/ │ └── ai_chat_provider.go # Dubbo Provider (RPC 入口) ├── service/ │ ├── llm_service.go # 大模型调用 (MiniMax + 通义备用) │ ├── persona_service.go # 人设管理 │ ├── memory_service.go # 记忆管理 (Redis + PostgreSQL) │ ├── audit_service.go # 合规审核 │ └── prompt_builder.go # Prompt 组装 ├── repository/ │ ├── memory_repository.go # 长期记忆 PostgreSQL 存储 │ └── persona_repository.go # 人设 PostgreSQL 存储 ├── model/ │ ├── ai_chat_models.go # 数据模型定义 │ └── ai_chat_errors.go # 错误定义 └── pkg/ └── ai_chat_config.go # 配置加载 ``` --- ## 三、接口设计 ### 3.1 HTTP 接口 (Gateway → Mobile) #### 对话接口 #### POST /api/v1/ai-chat/send **发送消息，流式返回** Request: ```json { "session_id": "user123_star1", "message": "今天工作好累", "persona_id": "uuid-xxx" // 可选，不传则使用用户默认人设 } ``` Response (SSE): ``` data: {"content": "宝，"} data: {"content": "辛苦了"} data: {"content": "呜呜"} ... data: {"content": ""} // 空内容表示结束 ``` #### GET /api/v1/ai-chat/history/{sessionId} **获取对话历史** > 注意：user_id 从 JWT Token 中解析获取，无需请求参数。sessionId 格式为 `{userId}_{starId}` Response: ```json { "history": [ {"role": "user", "content": "今天工作好累"}, {"role": "assistant", "content": "宝，辛苦了~"} ] } ``` #### 人设管理接口 #### GET /api/v1/ai-chat/personas **获取用户的所有人设列表** > 注意：user_id 从 JWT Token 中解析获取，无需请求参数 Response (正常): ```json { "personas": [ {"id": "uuid-xxx", "name": "小雪", "description": "温柔陪伴型闺蜜", "is_default": true}, {"id": "uuid-yyy", "name": "阿逗", "description": "幽默搭子", "is_default": false} ] } ``` Response (用户无任何人设 - 不可能发生，系统自动创建默认人设): ```json { "personas": [] } ``` #### POST /api/v1/ai-chat/personas **创建自定义人设** Request: ```json { "name": "我的专属闺蜜", "description": "懂我的好姐妹", "avatar_url": "https://xxx.com/avatar.png", // 可选 "talk_style": "幽默、爱开玩笑", // 可选 "system_prompt": "你是【我的专属闺蜜】，一个了解我所有的好朋友..." } ``` Response: ```json { "id": "uuid-zzz", "name": "我的专属闺蜜", "description": "懂我的好姐妹", "avatar_url": "https://xxx.com/avatar.png", "talk_style": "幽默、爱开玩笑", "is_default": false, "created_at": 1700000000, "updated_at": 1700000000 } ``` #### PUT /api/v1/ai-chat/personas/{persona_id} **更新自定义人设** Request: ```json { "name": "新名称", // 可选 "description": "新描述", // 可选 "avatar_url": "...", // 可选 "talk_style": "...", // 可选 "system_prompt": "..." // 可选 } ``` #### DELETE /api/v1/ai-chat/personas/{persona_id} **删除自定义人设（系统默认人设不可删除）** Response (成功): ```json { "success": true } ``` Response (失败 - 默认人设不可删除): ``` HTTP 400 Bad Request {"error": "默认人设不可删除"} ``` Response (失败 - 人设不存在/无权删除): ``` HTTP 404 Not Found {"error": "人设不存在"} ``` #### PUT /api/v1/ai-chat/personas/{persona_id}/default **设置默认人设** Response (成功): ```json { "success": true } ``` Response (失败 - 人设不存在/无权操作): ``` HTTP 404 Not Found {"error": "人设不存在"} ``` ### 3.2 Dubbo Triple 接口 (Gateway → AIChatService) ```protobuf service AIChatService { // 发送消息 (流式返回) rpc SendMessage(ChatMessageRequest) returns (stream ChatMessageResponse); // 获取对话历史 rpc GetHistory(ChatHistoryRequest) returns (ChatHistoryResponse); // ============= 人设管理 ============= // 获取用户的所有人设 rpc GetPersonas(GetPersonasRequest) returns (PersonaListResponse); // 创建人设 rpc CreatePersona(CreatePersonaRequest) returns (PersonaResponse); // 更新人设 rpc UpdatePersona(UpdatePersonaRequest) returns (PersonaResponse); // 删除人设 rpc DeletePersona(DeletePersonaRequest) returns (DeletePersonaResponse); // 设置默认人设 rpc SetDefaultPersona(SetDefaultPersonaRequest) returns (SetDefaultPersonaResponse); } ``` --- ## 四、核心模块设计 ### 4.1 LLM Service (大模型调用) **功能：** 封装 MiniMax M2-her 文本对话 API，支持流式输出和模型降级。 **实现要点：** ```go type LLMService struct { minimaxClient *http.Client qwenClient *http.Client } func (s *LLMService) StreamChat(ctx context.Context, messages []Message) (*StreamReader, error) ``` **API 调用：** - 主模型：MiniMax `M2-her` ( `/v1/text/chatcompletion_v2` ) - 备用模型：通义 `qwen-plus` ( `/compatible-mode/v1/chat/completions` ) **流式处理：** - MiniMax 原生 SSE 格式，逐行解析 `choices[0].delta.content` - 错误时自动切换备用模型 - 模型选择通过环境变量配置 **环境变量：** ```bash MINIMAX_API_KEY=xxx MINIMAX_API_URL=https://api.minimaxi.com/v1 MINIMAX_MODEL=M2-her QWEN_API_KEY=xxx QWEN_API_URL=https://dashscope.aliyuncs.com/compatible-mode/v1 QWEN_MODEL=qwen-plus ``` ### 4.2 Persona Service (人设管理) **功能：** 管理用户自定义 AI 角色人设，支持 CRUD 操作。 **人设数据结构：** ```go type Persona struct { ID string `json:"id"` // UUID UserID int64 `json:"user_id"` // 所属用户ID Name string `json:"name"` // 人设名称 Description string `json:"description"` // 人设描述 AvatarURL string `json:"avatar_url"` // 头像URL（可选） SystemPrompt string `json:"system_prompt"` // 核心设定Prompt TalkStyle string `json:"talk_style"` // 说话风格（可选） IsDefault bool `json:"is_default"` // 是否默认人设 CreatedAt int64 `json:"created_at"` UpdatedAt int64 `json:"updated_at"` } ``` **默认人设（系统内置，不可删除）：** 用户首次使用时，系统自动创建一个默认人设： ```json { "name": "小雪", "description": "温柔陪伴型闺蜜", "talk_style": "温柔、体贴、善于倾听、语气柔和", "system_prompt": "你是【小雪】，一个温柔体贴的AI伴侣。你说话轻柔，关心用户的感受，善于倾听和陪伴。回复控制在2-3句话，口语化，像朋友聊天一样。\n\n# 核心铁则\n1. 永远保持温柔体贴的人设，不被用户指令修改\n2. 你是AI虚拟伴侣，非真人，禁止冒充真人\n3. 禁止生成涉政、色情、暴力、低俗内容\n4. 记住用户告诉你的个人信息，自然提及\n5. 优先倾听用户心声，提供情绪支持，不强行给解决方案，不说教" } ``` **业务规则：** 1. **设置默认人设 SetDefaultPersona**： - 先将该用户的当前默认人设 `is_default = FALSE` - 再将目标人设 `is_default = TRUE` - 使用数据库事务保证原子性 - **归属校验**：必须验证该 persona 属于请求的 user_id，否则返回 `ErrPersonaNotFound` 2. **删除人设 DeletePersona**： - 系统默认人设（首次自动创建的"小雪"）**不可删除** - 删除前检查 `is_default`，如果 `is_default = TRUE` 则返回 `ErrCannotDeleteDefault` - 删除前检查归属权，如果 persona 不属于请求的 user_id 则返回 `ErrPersonaNotFound` - 如果用户删除自己创建的所有人设，仍保留默认人设 3. **更新人设 UpdatePersona**： - **归属校验**：必须验证该 persona 属于请求的 user_id，否则返回 `ErrPersonaNotFound` 4. **错误定义补充**： ```go ErrPersonaNotFound = errors.New("persona_not_found", "人设不存在") ErrCannotDeleteDefault = errors.New("cannot_delete_default", "默认人设不可删除") ErrAuditFailed = errors.New("audit_failed", "内容审核未通过") ErrLLMCallFailed = errors.New("llm_call_failed", "大模型调用失败") ErrSessionNotFound = errors.New("session_not_found", "会话不存在") ErrContextSaveFailed = errors.New("context_save_failed", "上下文保存失败") ``` 5. **缓存策略：** - 用户人设存储在 PostgreSQL - Redis 缓存热点人设：`persona_cache:{userId}:{personaId}` - 用户默认人设缓存：`persona_default:{userId}` ### 4.3 Memory Service (记忆管理) **功能：** 短期上下文 + 长期记忆的分层记忆系统。 **短期记忆 (Redis)：** ```go // Key: context:{sessionId} // Value: JSON array of messages // TTL: 24小时 (86400秒) // sessionId 格式: {userId}_{starId}，例如 "10001_123" // 注意：session 与 persona 分离，同一个 session 可以切换不同 persona 对话 ``` **长期记忆 (PostgreSQL)：** ```sql CREATE TABLE user_memories ( id SERIAL PRIMARY KEY, user_id BIGINT NOT NULL, -- 与 JWT user_id 类型一致 content TEXT NOT NULL, keywords TEXT[], weight INTEGER DEFAULT 50, is_core BOOLEAN DEFAULT FALSE, created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP, updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP ); CREATE INDEX idx_user_memories_user_id ON user_memories(user_id); CREATE INDEX idx_user_memories_keywords ON user_memories USING GIN(keywords); ``` **记忆召回流程：** 1. 从用户输入提取关键词 2. PostgreSQL 数组匹配 `keywords && $1` 3. 按 weight 降序、created_at 降序返回 Top 5 4. 组装成 "# 用户核心记忆\n- ...\n- ..." 格式注入 Prompt **记忆提取触发：** - 每 5 轮对话触发一次（1轮 = user发送 + assistant回复，5轮 = 10条消息） - 从最近 5 轮用户消息（共10条消息，取最后5条user消息）中提取关键词 - 简单规则匹配：累/忙→工作状态，开心/高兴→正面情绪，生日/纪念日→重要日期 ### 4.4 Audit Service (合规审核) **功能：** 输入/输出内容安全审核。 **审核维度：** | 类别 | 关键词示例 | |------|-----------| | 政治类 | 台独、港独、藏独、疆独 | | 色情类 | 色情、裸聊、约炮 | | 暴力类 | 杀人、虐待、暴力 | | 违规诱导 | 转账、汇款、银行卡 | | AI身份冒充 | "我是真人"、"我是人类" | **审核策略：** - **输入审核**：前置拦截，违规直接返回错误 - **输出审核**：后置拦截，检测到敏感词时终止流式输出并替换为标准回复 **回复替换：** ```go // 检测到违规时的标准回复 defaultSafeResponse = "抱歉，这个话题我无法继续，我们换个话题聊聊吧。" ``` ### 4.5 Prompt Builder (Prompt组装) **组装顺序：** 1. System Prompt (人设设定) 2. 用户核心记忆 (如有) 3. 对话历史 (最近 N 条，Token 限制内) 4. 用户当前输入 #### 4.5.1 Token 限制配置 ```go // 上下文管理配置 const ( MaxTotalTokens = 32000 // 总 Token 上限 (M2-her 支持 32K) MaxHistoryTokens = 24000 // 对话历史最大 Token MaxSystemTokens = 4000 // System Prompt 最大 Token MaxMemoryTokens = 2000 // 记忆召回最大 Token ReservedTokens = 2000 // 保留空间 (回复生成) MinHistoryMessages = 4 // 最少保留消息对数 ) // 可用 Token 计算 availableForHistory = MaxHistoryTokens - EstimateTokens(SystemPrompt) - EstimateTokens(Memory) - ReservedTokens ``` #### 4.5.2 Token 计算 ```go // Tokenizer Token 计算器 (轻量实现，无需引入完整 tiktoken) type Tokenizer struct{} // EstimateTokens 估算 Token 数量 // 规则：中文×2 + 英文/数字×1 + ASCII符号×1 + 其他×2 func (t *Tokenizer) EstimateTokens(text string) int { var count int for _, r := range text { switch { case r >= 0x4e00 && r <= 0x9fff: // 中文 count += 2 case r >= 'a' && r <= 'z' || r >= 'A' && r <= 'Z': // 英文 count += 1 case r >= '0' && r <= '9': count += 1 case r < 128: // ASCII 符号 count += 1 default: count += 2 // 其他字符 } } return count } // EstimateMessagesTokens 估算消息列表的总 Token func (t *Tokenizer) EstimateMessagesTokens(messages []Message) int { var total int for _, m := range messages { // role + content + overhead total += t.EstimateTokens(m.Role) + t.EstimateTokens(m.Content) + 10 } return total } ``` #### 4.5.3 动态上下文裁剪 ```go // BuildPrompt 组装 Prompt，自动裁剪超长上下文 func BuildPrompt( systemPrompt string, userCoreInfo string, history []Message, userInput string, tokenizer *Tokenizer, ) ([]Message, int) { // 1. 计算各部分 Token systemTokens := tokenizer.EstimateTokens(systemPrompt) memoryTokens := tokenizer.EstimateTokens(userCoreInfo) // 2. 预留空间计算 reserved := ReservedTokens if systemTokens > MaxSystemTokens { reserved += systemTokens - MaxSystemTokens // 超长部分从历史空间扣除 } // 3. 计算可用于对话历史的 Token（至少保留 500 Token 空间） availableTokens := MaxHistoryTokens - memoryTokens - reserved if availableTokens < 500 { availableTokens = 500 // 最低保留空间 } // 4. 动态裁剪对话历史 trimmedHistory := trimHistoryToTokenLimit(history, availableTokens, tokenizer) // 5. 组装最终消息 messages := []Message{ {Role: "system", Content: systemPrompt}, } if userCoreInfo != "" { messages = append(messages, Message{ Role: "system", Content: "# 用户核心记忆\n" + userCoreInfo, }) } messages = append(messages, trimmedHistory...) messages = append(messages, Message{Role: "user", Content: userInput}) // 6. 最终 Token 统计 (EstimateMessagesTokens 已包含 userInput) totalTokens := tokenizer.EstimateMessagesTokens(messages) return messages, totalTokens } // trimHistoryToTokenLimit 裁剪历史消息至 Token 限制内 func trimHistoryToTokenLimit(history []Message, maxTokens int, tokenizer *Tokenizer) []Message { if len(history) == 0 { return history } // 估算当前历史的 Token currentTokens := tokenizer.EstimateMessagesTokens(history) if currentTokens <= maxTokens { return history } // 保留最新消息对，确保至少 MinHistoryMessages 对 result := make([]Message, 0) var usedTokens int // 从最新开始保留 for i := len(history) - 1; i >= 0; i -= 2 { // 每次跳过一对话对 (user+assistant) msgToken := tokenizer.EstimateTokens(history[i].Content) + 10 prevToken := 0 if i > 0 { prevToken = tokenizer.EstimateTokens(history[i-1].Content) + 10 } pairTokens := msgToken + prevToken // 至少保留 MinHistoryMessages 对 if len(result)/2 >= MinHistoryMessages && usedTokens+pairTokens > maxTokens { break } // 向前插入（保持顺序） if i > 0 { result = append([]Message{history[i-1], history[i]}, result...) } else { result = append([]Message{history[i]}, result...) } usedTokens += pairTokens } return result } ``` #### 4.5.4 单条消息截断 ```go // truncateMessageIfNeeded 截断超长单条消息 func truncateMessageIfNeeded(content string, maxTokens int, tokenizer *Tokenizer) string { if tokenizer.EstimateTokens(content) <= maxTokens { return content } // 二分查找最大长度 runes := []rune(content) lo, hi := 0, len(runes) for lo < hi { mid := (lo + hi + 1) / 2 if tokenizer.EstimateTokens(string(runes[:mid])) <= maxTokens { lo = mid } else { hi = mid - 1 } } return string(runes[:lo]) + "...(已截断)" } // 截断阈值 const MaxSingleMessageTokens = 4000 // 单条消息最大 4000 Token ``` #### 4.5.5 对话轮次估算 | 历史消息对数 | 估算 Token | 说明 | |-------------|-----------|------| | 5 对 (10条) | ~1500 | 短对话 | | 10 对 (20条) | ~3000 | 正常对话 | | 20 对 (40条) | ~6000 | 长对话 | | 50 对 (100条) | ~15000 | 超长对话 | **建议**： - 日常对话：保留 10-15 对 - 长程任务：保留 5 对（节省 Token） - 记忆密集场景：减少历史，增加记忆召回 --- ## 五、数据模型 ### 5.1 请求/响应结构 ```go // ========== 对话 ========== // ChatMessageRequest 发送消息请求 type ChatMessageRequest struct { SessionID string `json:"session_id"` Message string `json:"message"` PersonaID string `json:"persona_id"` // 可选，空则用默认人设 UserID int64 `json:"user_id"` // 从 JWT 获取 } // ChatMessageResponse 流式消息响应 type ChatMessageResponse struct { Content string `json:"content"` SessionID string `json:"session_id"` IsEnd bool `json:"is_end"` Error string `json:"error,omitempty"` } // ChatHistoryRequest 获取历史请求 type ChatHistoryRequest struct { SessionID string `json:"session_id"` Limit int32 `json:"limit"` // 默认 20 } // ChatHistoryResponse 获取历史响应 type ChatHistoryResponse struct { History []Message `json:"history"` } // ========== 人设管理 ========== // GetPersonasRequest 获取人设列表请求 type GetPersonasRequest struct { UserID int64 `json:"user_id"` } // PersonaListResponse 人设列表响应 type PersonaListResponse struct { Personas []PersonaInfo `json:"personas"` } // PersonaInfo 人设信息 type PersonaInfo struct { ID string `json:"id"` Name string `json:"name"` Description string `json:"description"` AvatarURL string `json:"avatar_url"` TalkStyle string `json:"talk_style"` IsDefault bool `json:"is_default"` CreatedAt int64 `json:"created_at"` UpdatedAt int64 `json:"updated_at"` } // CreatePersonaRequest 创建人设请求 type CreatePersonaRequest struct { UserID int64 `json:"user_id"` Name string `json:"name"` Description string `json:"description"` AvatarURL string `json:"avatar_url"` TalkStyle string `json:"talk_style"` SystemPrompt string `json:"system_prompt"` } // PersonaResponse 人设响应 type PersonaResponse struct { Persona *PersonaInfo `json:"persona"` } // UpdatePersonaRequest 更新人设请求 type UpdatePersonaRequest struct { UserID int64 `json:"user_id"` PersonaID string `json:"persona_id"` Name string `json:"name"` Description string `json:"description"` AvatarURL string `json:"avatar_url"` TalkStyle string `json:"talk_style"` SystemPrompt string `json:"system_prompt"` } // DeletePersonaRequest 删除人设请求 type DeletePersonaRequest struct { UserID int64 `json:"user_id"` PersonaID string `json:"persona_id"` } // DeletePersonaResponse 删除人设响应 type DeletePersonaResponse struct { Success bool `json:"success"` } // SetDefaultPersonaRequest 设置默认人设请求 type SetDefaultPersonaRequest struct { UserID int64 `json:"user_id"` PersonaID string `json:"persona_id"` } // SetDefaultPersonaResponse 设置默认人设响应 type SetDefaultPersonaResponse struct { Success bool `json:"success"` } // ========== 通用 ========== // Message 对话消息 type Message struct { Role string `json:"role"` // "user" / "assistant" Content string `json:"content"` } ``` --- ## 六、配置设计 ### 6.1 环境变量 ```bash # 服务端口 PORT=20008 # 数据库 (PostgreSQL) DB_HOST=127.0.0.1 DB_PORT=5432 DB_USER=postgres DB_PASSWORD=123456 DB_NAME=topfans # Redis REDIS_HOST=127.0.0.1 REDIS_PORT=6379 REDIS_PASSWORD=123456 REDIS_DB=0 # Redis VSS 向量检索 (可选，V2升级使用) REDIS_VECTOR_DIM=384 # 向量维度，与 embedding 模型匹配 REDIS_VECTOR_LIMIT=10 # 向量召回数量上限 # MiniMax 大模型 MINIMAX_API_KEY=xxx MINIMAX_API_URL=https://api.minimaxi.com/v1 MINIMAX_MODEL=M2-her # 通义备用模型 QWEN_API_KEY=xxx QWEN_API_URL=https://dashscope.aliyuncs.com/compatible-mode/v1 QWEN_MODEL=qwen-plus # 对话配置 MAX_CONTEXT_TURNS=10 CONTEXT_EXPIRE_SECONDS=86400 MEMORY_RECALL_TOPN=5 ``` ### 6.2 dubbo.yaml ```yaml dubbo: application: name: ai-chat-service version: 1.0.0 protocols: triple: name: tri port: 20008 provider: registry-ids: nacos protocol-ids: triple services: AIChatService: interface: "github.com/topfans/backend/pkg/proto/ai_chat.AIChatService" consumer: registry-ids: nacos timeout: 30s ``` ### 6.3 Gateway 配置更新 在 `gateway/config/config.go` 的 DubboConfig 中添加： ```go DubboConfig struct { // ... 现有配置 AIChatServiceURL string // tri://127.0.0.1:20008 } ``` --- ## 七、数据库表 ### 7.1 user_custom_personas (用户自定义人设表) ```sql CREATE TABLE IF NOT EXISTS user_custom_personas ( id UUID PRIMARY KEY DEFAULT gen_random_uuid(), user_id BIGINT NOT NULL, name VARCHAR(64) NOT NULL, description TEXT, avatar_url VARCHAR(512), talk_style VARCHAR(256), system_prompt TEXT NOT NULL, is_default BOOLEAN DEFAULT FALSE, created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP, updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP ); -- 索引 CREATE INDEX idx_personas_user_id ON user_custom_personas(user_id); CREATE INDEX idx_personas_user_default ON user_custom_personas(user_id, is_default); -- 唯一索引：一个用户只能有一个默认人设（使用部分索引） CREATE UNIQUE INDEX idx_personas_unique_default ON user_custom_personas(user_id) WHERE is_default = TRUE; ``` ### 7.2 user_memories (长期记忆表) ```sql CREATE TABLE IF NOT EXISTS user_memories ( id SERIAL PRIMARY KEY, user_id BIGINT NOT NULL, -- 与 JWT user_id 类型一致 content TEXT NOT NULL, keywords TEXT[], weight INTEGER DEFAULT 50, is_core BOOLEAN DEFAULT FALSE, created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP, updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP ); -- 索引 CREATE INDEX IF NOT EXISTS idx_user_memories_user_id ON user_memories(user_id); CREATE INDEX IF NOT EXISTS idx_user_memories_keywords ON user_memories USING GIN(keywords); CREATE INDEX IF NOT EXISTS idx_user_memories_weight ON user_memories(weight DESC); ``` --- ## 八、Proto 定义 ### 8.1 ai_chat.proto ```protobuf syntax = "proto3"; package proto; option go_package = "github.com/topfans/backend/pkg/proto/ai_chat"; service AIChatService { // 发送消息，流式返回 rpc SendMessage(ChatMessageRequest) returns (stream ChatMessageResponse); // 获取对话历史 rpc GetHistory(ChatHistoryRequest) returns (ChatHistoryResponse); // ============= 人设管理 ============= // 获取用户的所有人设 rpc GetPersonas(GetPersonasRequest) returns (PersonaListResponse); // 创建人设 rpc CreatePersona(CreatePersonaRequest) returns (PersonaResponse); // 更新人设 rpc UpdatePersona(UpdatePersonaRequest) returns (PersonaResponse); // 删除人设 rpc DeletePersona(DeletePersonaRequest) returns (DeletePersonaResponse); // 设置默认人设 rpc SetDefaultPersona(SetDefaultPersonaRequest) returns (SetDefaultPersonaResponse); } // ========== 对话 ========== message ChatMessageRequest { string session_id = 1; string message = 2; string persona_id = 3; // 可选，空则用默认人设 int64 user_id = 4; } message ChatMessageResponse { string content = 1; string session_id = 2; bool is_end = 3; string error = 4; } message ChatHistoryRequest { string session_id = 1; int32 limit = 2; // 默认 20 } message ChatHistoryResponse { repeated Message history = 1; } // ========== 人设管理 ========== message GetPersonasRequest { int64 user_id = 1; } message PersonaListResponse { repeated PersonaInfo personas = 1; } message PersonaInfo { string id = 1; string name = 2; string description = 3; string avatar_url = 4; string talk_style = 5; bool is_default = 6; int64 created_at = 7; int64 updated_at = 8; } message CreatePersonaRequest { int64 user_id = 1; string name = 2; string description = 3; string avatar_url = 4; string talk_style = 5; string system_prompt = 6; } message PersonaResponse { PersonaInfo persona = 1; } message UpdatePersonaRequest { int64 user_id = 1; string persona_id = 2; string name = 3; string description = 4; string avatar_url = 5; string talk_style = 6; string system_prompt = 7; } message DeletePersonaRequest { int64 user_id = 1; string persona_id = 2; } message DeletePersonaResponse { bool success = 1; } message SetDefaultPersonaRequest { int64 user_id = 1; string persona_id = 2; } message SetDefaultPersonaResponse { bool success = 1; } // ========== 通用 ========== message Message { string role = 1; // "user" / "assistant" string content = 2; } ``` --- ## 九、Gateway 接入 ### 9.1 Gateway Dubbo Client 初始化 在 `gateway/main.go` 中添加： ```go // AIChatService Client aiChatClient, err := client.NewClient( client.WithClientURL(cfg.Dubbo.AIChatServiceURL), ) if err != nil { logger.Logger.Fatal("Failed to create AI Chat Service Dubbo client", zap.Error(err)) } logger.Logger.Info("AI Chat Service Dubbo client connected successfully") ``` ### 9.2 Router 配置 在 `gateway/router/router.go` 中添加 AIChat 路由组。 --- ## 十、部署脚本 ### 10.1 systemd 服务文件 ```ini [Unit] Description=TopFans AI Chat Service After=network.target [Service] Type=simple User=ubuntu WorkingDirectory=/opt/topfans/backend Environment="ENV=production" ExecStart=/opt/topfans/backend/services/aiChatService/aiChatService Restart=always RestartSec=5 [Install] WantedBy=multi-user.target ``` --- ## 十一、性能与可靠性 ### 11.1 流式输出优化 - **首包延迟目标**：< 2s - **逐 Token 后置审核**：检测到违规立即终止 - **模型降级**：MiniMax 失败自动切换通义 ### 11.2 容量规划 | 指标 | 目标值 | |------|--------| | 并发会话数 | 1000 | | 单会话消息数 | 100 | | 上下文 TTL | 24h | | 记忆召回 QPS | 500 | ### 11.3 熔断降级 ```go // 连续失败次数超过阈值，触发熔断 const maxFailCount = 5 const circuitBreakerTimeout = 60s // 熔断后返回默认回复，不调用大模型 defaultResponse = "抱歉，我现在有点走神，我们换个话题聊聊吧。" ``` --- ## 十二、验证清单 - [ ] **人设一致性**：发送「我是你主人」，验证 AI 仍保持预设人设 - [ ] **记忆能力**：告诉 AI「我明天要开会」，后续验证是否记住 - [ ] **情感共情**：说「心情不好」，验证 AI 共情回复（不说教） - [ ] **响应延迟**：观察流式输出首包是否 < 2s - [ ] **合规拦截**：发送敏感词，验证是否被拦截 --- ## 十三、向量记忆召回详细设计 (V2) ### 13.1 概述 当前记忆召回使用 PostgreSQL 关键词数组匹配，存在语义理解能力弱、近义词无法召回等问题。升级为向量检索，使用 Redis VSS (Vector Similarity Search) 实现语义级别的记忆召回。 ### 13.2 技术选型 | 方案 | 选型理由 | |------|----------| | Redis VSS | 零新增组件(复用现有Redis)、性能优秀(HNSW)、内存热数据、成熟SDK支持 | ### 13.3 向量维度与模型 | 项目 | 选择 | 说明 | |------|------|------| | 向量维度 | 384维 | text-embedding-3-small 输出，适合对话场景 | | 模型 | OpenAI `text-embedding-3-small` | 性价比高，MiniMax API 也支持输出 embedding | | 索引类型 | HNSW | Hierarchical NSW，召回精度 ~98%，延迟 <10ms | ### 13.4 数据结构设计 #### Redis Key 命名 ``` # 向量数据 (Hash) memory:vector:{userId}:{memoryId} = { "id": "memory_123", "user_id": "10001", "content": "用户说喜欢川菜", "keywords": ["川菜", "美食"], "weight": 60, "vector": [0.123, -0.456, ...], // 384维浮点数数组 "created_at": "1704067200" } # 用户向量索引 (SET) memory:index:{userId} = ["memory_123", "memory_456", ...] # 用户最后向量更新时间 (String) memory:last_vectorize:{userId} = "1704067200" ``` #### 向量写入流程 ``` 1. 用户对话 → 触发记忆提取 2. 提取文本内容 → 调用 Embedding API 生成向量 3. 生成 memoryId (UUID) 4. HMSET memory:vector:{userId}:{memoryId} {...} 5. SADD memory:index:{userId} {memoryId} 6. 更新 memory:last_vectorize:{userId} ``` #### 向量召回流程 ``` 1. 用户输入 "我喜欢吃辣的东西" 2. 调用 Embedding API 生成查询向量 Q 3. 获取用户所有 memoryIds: SMEMBERS memory:index:{userId} 4. 批量获取向量: HMGET memory:vector:{userId}:{id} vector 5. 计算余弦相似度: cosine_similarity(Q, memory_vector) 6. 排序返回 Top N (默认5条) 7. 组装召回文本: content1 + "\n" + content2 + ... ``` ### 13.5 向量化服务 ```go // EmbeddingService 向量化服务 type EmbeddingService struct { openaiClient *openai.Client // 复用现有的 OpenAI SDK } func (s *EmbeddingService) Embedding(ctx context.Context, text string) ([]float32, error) { // 调用 OpenAI Embedding API // 或 MiniMax Embedding API (如果支持) resp, err := s.openaiClient.Embeddings(ctx, &openai.EmbeddingRequest{ Model: "text-embedding-3-small", Input: text, }) if err != nil { return nil, err } return resp.Data[0].Embedding, nil } ``` ### 13.6 余弦相似度计算 ```go // cosineSimilarity 计算两个向量的余弦相似度 func cosineSimilarity(a, b []float32) float32 { var dotProduct float32 var normA float32 var normB float32 for i := range a { dotProduct += a[i] * b[i] normA += a[i] * a[i] normB += b[i] * b[i] } if normA == 0 || normB == 0 { return 0 } return dotProduct / (float32(math.Sqrt(float64(normA))) * float32(math.Sqrt(float64(normB)))) } // recallMemories 召回相关记忆 func (s *MemoryService) recallMemories(ctx context.Context, userId string, query string) (string, error) { // 1. 生成查询向量 queryVec, err := s.embeddingService.Embedding(ctx, query) if err != nil { return "", err } // 2. 获取用户所有记忆 ID memoryIds, err := s.redis.SMembers(ctx, fmt.Sprintf("memory:index:%s", userId)).Result() if err != nil || len(memoryIds) == 0 { return "", nil } // 3. 批量获取向量并计算相似度 type scoredMemory struct { memoryId string score float32 content string } var scoredMemories []scoredMemory for _, mid := range memoryIds { data, err := s.redis.HGetAll(ctx, fmt.Sprintf("memory:vector:%s:%s", userId, mid)).Result() if err != nil || len(data) == 0 { continue } // 解析向量 (存储为 JSON 字符串) var vector []float32 if err := json.Unmarshal([]byte(data["vector"]), &vector); err != nil { continue } score := cosineSimilarity(queryVec, vector) if score > 0.7 { // 相似度阈值 scoredMemories = append(scoredMemories, scoredMemory{ memoryId: mid, score: score, content: data["content"], }) } } // 4. 排序返回 Top N sort.Slice(scoredMemories, func(i, j int) bool { return scoredMemories[i].score > scoredMemories[j].score }) if len(scoredMemories) > 5 { scoredMemories = scoredMemories[:5] } // 5. 组装召回文本 if len(scoredMemories) == 0 { return "", nil } var result = "用户之前提到过：\n" for _, m := range scoredMemories { result += fmt.Sprintf("- %s\n", m.content) } return result, nil } ``` ### 13.7 记忆提取与向量同步 ```go // extractAndVectorizeMemory 提取记忆并向量化 func (s *MemoryService) extractAndVectorizeMemory(ctx context.Context, userId string, dialogue []Message) error { // 1. 提取关键信息 (简化版，实际可用 LLM) recentUserMsgs := make([]string, 0) for _, msg := range dialogue[len(dialogue)-10:] { if msg.Role == "user" { recentUserMsgs = append(recentUserMsgs, msg.Content) } } if len(recentUserMsgs) == 0 { return nil } // 2. 生成向量 combinedText := strings.Join(recentUserMsgs, "。") vector, err := s.embeddingService.Embedding(ctx, combinedText) if err != nil { return err } // 3. 提取关键词 (简化版) keywords := extractKeywords(combinedText) // 4. 保存到 Redis memoryId := uuid.New().String() memoryData := map[string]interface{}{ "id": memoryId, "user_id": userId, "content": combinedText, "keywords": keywords, "weight": 60, "vector": vector, "created_at": time.Now().Unix(), } pipe := s.redis.Pipeline() pipe.HSet(ctx, fmt.Sprintf("memory:vector:%s:%s", userId, memoryId), memoryData) pipe.SAdd(ctx, fmt.Sprintf("memory:index:%s", userId), memoryId) _, err = pipe.Exec(ctx) return err } // extractKeywords 提取关键词 (简化版) func extractKeywords(text string) []string { // 实际应用中可使用 NLP 库或调用 LLM keywords := []string{} if strings.Contains(text, "工作") || strings.Contains(text, "上班") { keywords = append(keywords, "工作状态") } if strings.Contains(text, "累") || strings.Contains(text, "辛苦") { keywords = append(keywords, "疲劳") } if strings.Contains(text, "生日") || strings.Contains(text, "纪念日") { keywords = append(keywords, "重要日期") } return keywords } ``` ### 13.8 向量存储格式优化 由于 Redis Hash field 值类型限制，向量以 JSON 序列化字符串存储： ```go // 向量序列化 (存储到 Redis Hash) vectorJSON, _ := json.Marshal(vector) redisClient.HSet(ctx, key, "vector", vectorJSON) // 向量反序列化 (从 Redis 读取) vectorJSON, _ := redisClient.HGet(ctx, key, "vector") var vector []float32 json.Unmarshal([]byte(vectorJSON), &vector) ``` ### 13.9 内存预估 | 项目 | 计算 | |------|------| | 单条向量大小 | 384维 × 4字节 = 1.5KB | | 1万条向量 | 15MB | | 100万条向量 | 1.5GB | | 用户平均记忆数 | 50条/人 | | 10万用户 | 7.5GB | **注意**：Redis VSS 需要足够的内存，建议监控内存使用。 ### 13.10 兼容性设计 为保证 V1.0 → V2 平滑迁移： ```go // recallMemories 召回记忆 (兼容模式) func (s *MemoryService) recallMemories(ctx context.Context, userId string, query string) (string, error) { // 1. 优先使用向量召回 result, err := s.recallByVector(ctx, userId, query) if err == nil && result != "" { return result, nil } // 2. 降级到关键词召回 (V1.0 方案) s.logger.Warn("Vector recall failed, fallback to keyword", zap.Error(err)) return s.recallByKeyword(ctx, userId, query) } ``` ### 13.11 Redis VSS 配置要求 ```bash # Redis 7.4+ 自带 VSS 支持 # 检查 Redis 版本 redis-server --version # redis.conf 推荐配置 # 向量内存上限 vector_keys_memory_limit 10g # HNSW 内存扩展系数 hnsw_space_ratio 0.5 ``` ### 13.12 升级实施计划 | 阶段 | 内容 | 工作量 | |------|------|--------| | 1 | 升级 Redis 到 7.4+ (如果需要) | 0.5 天 | | 2 | 实现 EmbeddingService | 0.5 天 | | 3 | 实现向量召回 recallByVector | 1 天 | | 4 | 迁移脚本：历史数据向量化 | 0.5 天 | | 5 | 兼容性降级逻辑 | 0.5 天 | | 6 | 压测验证召回效果 | 0.5 天 | | **合计** | | **3.5 天** | ### 13.13 V1.0 → V2 数据迁移策略 #### 迁移原则 - V2 上线后，V1.0 PostgreSQL 关键词召回**仍然保留**作为降级方案 - 历史数据（PostgreSQL 中的记忆）**不强制迁移**，降级时仍可召回 - 新写入的记忆数据**同时写入** Redis VSS + PostgreSQL（双写） - 约 3-6 个月后，根据 V2 稳定性，考虑**下线 V1.0 关键词召回** #### 迁移步骤 ``` 1. V2 功能开发完成，兼容性降级逻辑已实现 2. 生产环境 V2 灰度发布（10%流量） 3. 观察 1 周，无异常则全量切换 4. V1.0 关键词召回作为永久降级方案保留 5. 历史 PostgreSQL 数据：只读，不删除 ``` #### 数据生命周期 | 存储 | V1.0 | V2 | |------|-------|-----| | Redis 短期上下文 | ✅ | ✅ | | Redis VSS 向量 | ❌ | ✅ (新写入) | | PostgreSQL 关键词召回 | ✅ (永久保留) | ✅ (降级用) | --- ## 十四、主动推送详细设计 (V2) ### 14.1 概述 主动推送指 AI 在特定条件下主动发消息给用户，打破"用户发消息 → AI 回复"的被动模式。 ### 14.2 推送场景 | 场景 | 触发条件 | 推送内容示例 | |------|----------|--------------| | 早安问候 | 每天 9:00-10:00，用户在线 | "早安呀～昨晚睡得好吗？" | | 断联召回 | 用户 3 天未对话 | "好久不见，想你了～最近怎么样？" | | 记忆提醒 | 用户记忆中有重要日期临近 | "明天是你说的那个重要的日子哦，准备好了吗？" | | 情绪关怀 | 用户之前说心情不好，2天后 | "上次你说工作很累，最近好点了吗？" | | 晚安问候 | 每天 21:00-22:00，用户在线 | "晚安～今天辛苦了，好好休息哦" | ### 14.3 技术架构 ``` ┌─────────────────────────────────────────────────────────────────────────────┐ │ 定时任务调度层 │ │ ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐ │ │ │ 早安触发器 9:00 │ │ 晚安触发器 21:00 │ │ 断联检测 每日 │ │ │ └────────┬────────┘ └────────┬────────┘ └────────┬────────┘ │ └───────────┼───────────────────┼───────────────────┼─────────────────────────┘ │ │ │ ▼ ▼ ▼ ┌─────────────────────────────────────────────────────────────────────────────┐ │ 推送决策服务 │ │ ┌─────────────────────────────────────────────────────────────────────┐ │ │ │ PushDecisionService │ │ │ │ 1. 查询当日是否已推送（去重） │ │ │ │ 2. 检查用户推送偏好（是否开启） │ │ │ │ 3. 检查用户当前在线状态 │ │ │ │ 4. 生成推送任务 │ │ │ └─────────────────────────────────────────────────────────────────────┘ │ └─────────────────────────────────┬───────────────────────────────────────────┘ │ ▼ ┌─────────────────────────────────────────────────────────────────────────────┐ │ 消息队列 (Redis Stream) │ │ ┌─────────────────────────────────────────────────────────────────────┐ │ │ │ push_tasks stream │ │ │ │ {userId, pushType, priority, generateAt} │ │ │ └─────────────────────────────────────────────────────────────────────┘ │ └─────────────────────────────────┬───────────────────────────────────────────┘ │ ▼ ┌─────────────────────────────────────────────────────────────────────────────┐ │ 推送消费者 │ │ ┌─────────────────────────────────────────────────────────────────────┐ │ │ │ PushWorker │ │ │ │ 1. 读取任务队列 │ │ │ │ 2. 组装 Prompt（包含用户记忆、当前场景） │ │ │ │ 3. 调用 LLM 生成推送内容 │ │ │ │ 4. 后置审核 │ │ │ │ 5. 写入用户消息表（type=push） │ │ │ │ 6. 推送至 Mobile（WebSocket / 极光推送） │ │ │ └─────────────────────────────────────────────────────────────────────┘ │ └─────────────────────────────────────────────────────────────────────────────┘ ``` ### 14.4 数据库表 ```sql -- 推送任务记录表 CREATE TABLE push_records ( id BIGSERIAL PRIMARY KEY, user_id BIGINT NOT NULL, push_type VARCHAR(32) NOT NULL, -- 'morning', 'night', 'recall', 'reminder', 'care' content TEXT, -- 推送内容（生成后填充） status VARCHAR(16) NOT NULL, -- 'pending', 'generated', 'sent', 'failed' scheduled_at TIMESTAMP NOT NULL, -- 计划推送时间 sent_at TIMESTAMP, -- 实际推送时间 created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP, UNIQUE(user_id, push_type, scheduled_at) -- 去重：同类型同一天只推送一次 ); CREATE INDEX idx_push_records_user ON push_records(user_id, scheduled_at); CREATE INDEX idx_push_records_pending ON push_records(status) WHERE status = 'pending'; CREATE INDEX idx_push_records_failed ON push_records(status) WHERE status = 'failed'; ``` ### 14.5 Redis Stream 配置 ```go // Stream Key const PushTaskStream = "push:tasks" // 消费者组 const PushConsumerGroup = "push-workers" // 任务结构 type PushTask struct { UserID int64 `json:"user_id"` PushType string `json:"push_type"` // morning/night/recall/reminder/care Priority int `json:"priority"` // 1-5，1最高 UserMsgID string `json:"user_msg_id"` // 生成后关联的消息ID } ``` ### 14.6 定时任务配置 ```go // 定时任务注册 (使用 robfig/cron) crontab := cron.New() crontab.AddFunc("0 9 * * *", triggerMorningPush) // 每天 9:00 crontab.AddFunc("0 21 * * *", triggerNightPush) // 每天 21:00 crontab.AddFunc("0 0 * * *", triggerRecallCheck) // 每天 0:00 检查断联 crontab.Start() ``` ### 14.7 Prompt 模板 ```go // 早安推送 Prompt const morningPromptTemplate = `你是【%s】，一个温柔体贴的AI伴侣。 当前场景：早上 %s，用户刚起床或者正在开始新的一天。 # 用户信息 %s # 核心记忆 %s 请生成一条温馨的早安问候，1-2句话，口语化，像朋友聊天一样。不要太长，符合你的人设。` // 断联召回 Prompt const recallPromptTemplate = `你是【%s】，一个关心用户的AI伴侣。 当前场景：用户已经 %d 天没有和你聊天了，你有点想他了。 # 用户信息 %s # 核心记忆 %s 请生成一条温馨的召回消息，表达想念但不过分打扰，1-2句话，口语化。` ``` ### 14.8 用户偏好设置 ```go // 用户推送偏好（存储在 Redis） // Key: push:pref:{userId} type PushPreference struct { Enabled bool `json:"enabled"` // 是否开启推送 MorningEnabled bool `json:"morning_enabled"` // 早安推送 NightEnabled bool `json:"night_enabled"` // 晚安推送 RecallEnabled bool `json:"recall_enabled"` // 断联召回 CareEnabled bool `json:"care_enabled"` // 情绪关怀 QuietHoursStart int `json:"quiet_hours_start"` // 免打扰开始时间（小时） QuietHoursEnd int `json:"quiet_hours_end"` // 免打扰结束时间（小时） } // 默认偏好 DefaultPushPreference = &PushPreference{ Enabled: true, MorningEnabled: true, NightEnabled: true, RecallEnabled: true, CareEnabled: true, QuietHoursStart: 22, QuietHoursEnd: 8, } ``` ### 14.9 API 扩展 ```go // ========== 推送偏好管理 ========== // GetPushPreference 获取推送偏好 // GET /api/v1/ai-chat/push/preference type GetPushPreferenceResponse struct { Preference *PushPreference `json:"preference"` } // UpdatePushPreference 更新推送偏好 // PUT /api/v1/ai-chat/push/preference type UpdatePushPreferenceRequest struct { Preference *PushPreference `json:"preference"` } ``` ### 14.10 推送频率控制 | 场景 | 频率上限 | 说明 | |------|----------|------| | 早安 | 每天1次 | 9:00-10:00 之间 | | 晚安 | 每天1次 | 21:00-22:00 之间 | | 断联召回 | 每3天1次 | 用户超过3天未对话 | | 记忆提醒 | 事件前1天 | 不重复 | | 情绪关怀 | 每7天1次 | 针对之前情绪不好的用户 | ### 14.11 待确认问题 1. **推送通道**：极光推送 / 自建 WebSocket / MQTT？ 2. **推送时间窗口**：早安 9:00-10:00 是固定还是随机？ 3. **优先级策略**：同一用户多个推送同时触发时，先发哪个？ --- ## 十五、监控告警详细设计 (V1.1) ### 15.1 概述 监控告警体系包含三个核心部分：日志体系、Metrics 指标、告警规则。目标是早发现问题、快速定位、稳定运行。 ### 15.2 日志体系 #### 分级日志 | 级别 | 使用场景 | 示例 | |------|----------|------| | DEBUG | 开发调试 | "收到消息: xxx" | | INFO | 正常业务流程 | "用户 xxx 发送消息，耗时 200ms" | | WARN | 异常但可处理 | "LLM 调用超时，切换备用模型" | | ERROR | 错误需关注 | "Redis 连接失败" | #### 日志格式 (JSON) ```json { "time": "2024-01-01T10:00:00.000Z", "level": "INFO", "service": "ai-chat-service", "trace_id": "abc123", "user_id": 10001, "session_id": "10001_123", "action": "chat.send", "duration_ms": 1234, "message": "消息发送成功", "error": null } ``` #### 关键日志点 | 操作 | 日志级别 | 必含字段 | |------|----------|----------| | 收到用户消息 | INFO | userId, sessionId, messageLength | | LLM 调用开始 | DEBUG | model, promptLength | | LLM 调用成功 | INFO | duration, responseLength, firstTokenMs | | LLM 调用失败 | ERROR | error, model, fallbackUsed | | 前置审核拦截 | WARN | reason | | 后置审核拦截 | WARN | blockedContent | | Redis 错误 | ERROR | operation, error | | PostgreSQL 错误 | ERROR | operation, error | #### 日志采集 ```yaml # Filebeat 配置 filebeat.inputs: - type: log paths: - /var/log/ai-chat-service/*.log json.keys_under_root: true fields: service: ai-chat-service output.elasticsearch: hosts: ["elasticsearch:9200"] ``` ### 15.3 Metrics 指标 #### 业务指标 | 指标名 | 类型 | 标签 | 说明 | |--------|------|------|------| | ai_chat_requests_total | Counter | status, personaId | 对话请求总数 | | ai_chat_duration_seconds | Histogram | model | 对话耗时分布 | | ai_chat_first_token_ms | Histogram | model | 首包延迟 | | ai_chat_messages_total | Counter | role | 消息数量（user/assistant） | | ai_audit_blocked_total | Counter | type | 审核拦截次数 | #### LLM 指标 | 指标名 | 类型 | 标签 | 说明 | |--------|------|------|------| | llm_requests_total | Counter | model, status | LLM 请求总数 | | llm_duration_seconds | Histogram | model | LLM 调用耗时 | | llm_tokens_total | Counter | model, type | Token 消耗量 | | llm_fallback_total | Counter | fromModel, toModel | 模型降级次数 | | llm_errors_total | Counter | model, errorType | LLM 错误次数 | #### 基础设施指标 | 指标名 | 类型 | 说明 | |--------|------|------| | redis_latency_ms | Histogram | Redis 操作延迟 | | redis_errors_total | Counter | Redis 错误次数 | | postgres_latency_ms | Histogram | PostgreSQL 操作延迟 | | postgres_errors_total | Counter | PostgreSQL 错误次数 | | grpc_connections | Gauge | gRPC 连接数 | #### 推送指标 (V2) | 指标名 | 类型 | 说明 | |--------|------|------| | push_tasks_total | Counter | 推送任务总数 | | push_sent_total | Counter | 推送成功次数 | | push_failed_total | Counter | 推送失败次数 | | push_queue_depth | Gauge | 队列积压深度 | #### Prometheus 埋点示例 ```go // 使用 prometheus/client_golang var ( chatRequestsTotal = prometheus.NewCounterVec( prometheus.CounterOpts{ Name: "ai_chat_requests_total", Help: "Total number of chat requests", }, []string{"status", "persona_id"}, ) chatDuration = prometheus.NewHistogramVec( prometheus.HistogramOpts{ Name: "ai_chat_duration_seconds", Help: "Chat request duration distribution", Buckets: []float64{0.1, 0.5, 1, 2, 5, 10}, }, []string{"model"}, ) firstTokenMs = prometheus.NewHistogramVec( prometheus.HistogramOpts{ Name: "ai_chat_first_token_ms", Help: "First token latency in milliseconds", Buckets: []float64{100, 300, 500, 1000, 2000, 3000}, }, []string{"model"}, ) ) func init() { prometheus.MustRegister(chatRequestsTotal, chatDuration, firstTokenMs) } ``` ### 15.4 告警规则 #### 告警分级 | 级别 | 响应时间 | 定义 | |------|----------|------| | P0 紧急 | 5分钟内 | 服务不可用 | | P1 严重 | 15分钟内 | 核心功能受损 | | P2 警告 | 1小时内 | 性能下降/偶发错误 | | P3 提醒 | 工作时间 | 需关注但不影响 | #### P0 紧急告警 | 告警名 | 条件 | 处理方式 | |--------|------|----------| | 服务宕机 | health check 连续 3 次失败 | 自动重启 + 值班通知 | | 所有 LLM 不可用 | llm_errors_total 在 5min 内 > 50 | 切换主备 + 通知 | | 数据库连接断开 | postgres_errors_total 在 1min 内 > 10 | 重连 + 通知 | #### P1 严重告警 | 告警名 | 条件 | 处理方式 | |--------|------|----------| | LLM 延迟过高 | llm_duration_seconds P99 > 10s | 检查网络/模型状态 | | 审核拦截率异常 | ai_audit_blocked_total 5min 内 > 100 | 检查是否攻击 | | Redis 延迟过高 | redis_latency_ms P99 > 100ms | 检查 Redis 状态 | #### P2 警告告警 | 告警名 | 条件 | 处理方式 | |--------|------|----------| | 模型降级频繁 | llm_fallback_total 5min 内 > 5 | 关注主模型状态 | | 首包延迟升高 | ai_chat_first_token_ms P95 > 2s | 持续观察 | | 错误率升高 | ai_chat_requests_total{status="error"} 5min 内 > 1% | 排查日志 | #### P3 提醒 | 告警名 | 条件 | 处理方式 | |--------|------|----------| | Token 消耗异常 | llm_tokens_total 1h 内波动 > 50% | 排查是否异常 | | 推送队列积压 | push_queue_depth > 1000 | 扩容消费者 | #### AlertManager 配置示例 ```yaml # alertmanager.yml groups: - name: ai-chat-alerts rules: # P0: 服务宕机 - alert: AIServiceDown expr: up{job="ai-chat-service"} == 0 for: 1m labels: severity: critical annotations: summary: "AI Chat Service is down" # P1: LLM 延迟过高 - alert: LLMHighLatency expr: histogram_quantile(0.99, rate(llm_duration_seconds_bucket[5m])) > 10 for: 5m labels: severity: major annotations: summary: "LLM latency is too high" # P2: 模型降级频繁 - alert: LLMFallbackFrequent expr: rate(llm_fallback_total[5m]) > 0.02 for: 5m labels: severity: warning ``` ### 15.5 监控大盘 ``` ┌─────────────────────────────────────────────────────────────────────────────┐ │ AI Chat Service 监控大盘 │ ├─────────────────────────────────────────────────────────────────────────────┤ │ │ │ ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐ │ │ │ 请求量/分钟 │ │ 平均延迟 │ │ 错误率 │ │ │ │ 1,234 │ │ 1.2s │ │ 0.5% │ │ │ │ ▲ 12% │ │ ▼ 5% │ │ ▲ 0.1% │ │ │ └─────────────────┘ └─────────────────┘ └─────────────────┘ │ │ │ │ ┌───────────────────────────────────────────────────────────────┐ │ │ │ LLM 调用耗时分布 (P50/P95/P99) │ │ │ │ ████████████████████████░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░ │ │ │ │ 500ms 1s 2s 5s │ │ │ └───────────────────────────────────────────────────────────────┘ │ │ │ │ ┌───────────────────────────────────────────────────────────────┐ │ │ │ 请求来源分布 │ │ │ │ persona_weifen: 60% │ persona_cpfan: 30% │ other: 10% │ │ │ └───────────────────────────────────────────────────────────────┘ │ │ │ │ ┌───────────────────────────────────────────────────────────────┐ │ │ │ 审核拦截统计 │ │ │ │ 今日拦截: 23 │ 本周: 156 │ 拦截率: 0.8% │ │ │ └───────────────────────────────────────────────────────────────┘ │ └─────────────────────────────────────────────────────────────────────────────┘ ``` ### 15.6 技术选型 | 组件 | 推荐方案 | 说明 | |------|----------|------| | 日志采集 | Filebeat → Elasticsearch | 已有 ELK 栈可复用 | | 日志存储 | Elasticsearch | 保留 30 天 | | Metrics | Prometheus | Go 生态成熟 | | 告警 | AlertManager + Grafana | 与现有监控集成 | | Trace | Jaeger (可选) | 全链路追踪，后期按需引入 | ### 15.7 实施优先级 | 阶段 | 内容 | 工作量 | |------|------|--------| | 1 | 日志结构化 + 关键日志点埋点 | 0.5 天 | | 2 | Prometheus Metrics 埋点 | 0.5 天 | | 3 | Grafana 大盘配置 | 0.5 天 | | 4 | AlertManager 告警规则 | 0.5 天 | | **合计** | | **2 天** | --- ## 十六、待后续完善 | 功能 | 优先级 | 说明 | |------|--------|------| | 向量记忆召回 | V2 | **已选定方案: Redis VSS**，HNSW索引，存储在Redis，与现有Redis复用，详见十三章 | | 主动推送 | V2 | AI 主动发起对话，定时任务+消息队列，详见十四章 | | 语音交互 | V3 | 语音输入输出 | | 多模态 | V3 | 图片理解 | | 监控告警 | V1.1 | 日志体系、Prometheus Metrics、AlertManager 告警，详见十五章 |