223 lines
10 KiB
Markdown
223 lines
10 KiB
Markdown
# ai-service - Progress
|
||
|
||
---
|
||
|
||
## 📋 Context
|
||
|
||
- module: `ai-service`
|
||
- feature: `AISVC` (Python AI 中台)
|
||
- status: 🔄 进行中 (Phase 14 完成)
|
||
|
||
---
|
||
|
||
## 🔗 Spec References (SSOT)
|
||
|
||
- agents: `agents.md`
|
||
- contracting: `spec/contracting.md`
|
||
- requirements: `spec/ai-service/requirements.md`
|
||
- openapi_provider: `spec/ai-service/openapi.provider.yaml`
|
||
- design: `spec/ai-service/design.md`
|
||
- tasks: `spec/ai-service/tasks.md`
|
||
|
||
---
|
||
|
||
## 📊 Overall Progress (Phases)
|
||
|
||
- [x] Phase 1: 基础设施（FastAPI 框架与多租户基础） (100%) ✅
|
||
- [x] Phase 2: 存储与检索实现（Memory & Retrieval） (100%) ✅
|
||
- [x] Phase 3: 核心编排（Orchestrator & LLM Adapter） (100%) ✅
|
||
- [x] Phase 4: 流式响应（SSE 实现与状态机） (100%) ✅
|
||
- [x] Phase 5: 集成与冒烟测试（Quality Assurance） (100%) ✅
|
||
- [x] Phase 6: 前后端联调真实对接 (100%) ✅
|
||
- [x] Phase 7: 嵌入模型可插拔与文档解析 (100%) ✅
|
||
- [x] Phase 8: LLM 配置与 RAG 调试输出 (100%) ✅
|
||
- [x] Phase 9: 租户管理与 RAG 优化 (100%) ✅
|
||
- [x] Phase 10: Prompt 模板化 (80%) 🔄 (T10.1-T10.8 完成，T10.9-T10.10 待集成阶段)
|
||
- [x] Phase 11: 多知识库管理 (63%) 🔄 (T11.1-T11.5 完成，T11.6-T11.8 待集成阶段)
|
||
- [x] Phase 12: 意图识别与规则引擎 (71%) 🔄 (T12.1-T12.5 完成，T12.6-T12.7 待集成阶段)
|
||
- [x] Phase 13: 话术流程引擎 (0%) ⏳ 待处理
|
||
- [x] Phase 14: 输出护栏 (88%) ✅ (T14.1-T14.7 完成，T14.8 单元测试留到集成阶段)
|
||
|
||
---
|
||
|
||
## 🔄 Current Phase
|
||
|
||
### Goal
|
||
Phase 14 输出护栏核心功能已完成 (T14.1-T14.7)，T14.8（单元测试）留到集成阶段。
|
||
|
||
### Completed Tasks (Phase 14)
|
||
|
||
- [x] T14.1 定义 `ForbiddenWord` 和 `BehaviorRule` SQLModel 实体，创建数据库表 `[AC-AISVC-78, AC-AISVC-84]` ✅
|
||
- [x] T14.2 实现 `ForbiddenWordService`：禁词 CRUD + 命中统计 `[AC-AISVC-78, AC-AISVC-79, AC-AISVC-80, AC-AISVC-81]` ✅
|
||
- [x] T14.3 实现 `BehaviorRuleService`：行为规则 CRUD `[AC-AISVC-84, AC-AISVC-85]` ✅
|
||
- [x] T14.4 实现 `InputScanner`：用户输入前置禁词检测（仅记录，不阻断） `[AC-AISVC-83]` ✅
|
||
- [x] T14.5 实现 `OutputFilter`：LLM 输出后置过滤（mask/replace/block 三种策略） `[AC-AISVC-82]` ✅
|
||
- [x] T14.6 实现 Streaming 模式下的滑动窗口禁词检测 `[AC-AISVC-82]` ✅
|
||
- [x] T14.7 实现护栏管理 API：`/admin/guardrails` 相关端点 `[AC-AISVC-78~AC-AISVC-85]` ✅
|
||
|
||
### Pending Tasks (Phase 14 - 集成阶段)
|
||
|
||
- [ ] T14.8 编写输出护栏服务单元测试 `[AC-AISVC-78~AC-AISVC-85]`
|
||
|
||
---
|
||
|
||
## 🏗️ Technical Context
|
||
|
||
### Module Structure
|
||
|
||
- `ai-service/`
|
||
- `app/`
|
||
- `api/` - FastAPI 路由层
|
||
- `admin/guardrails.py` - 护栏管理 API ✅
|
||
- `models/` - Pydantic 模型和 SQLModel 实体
|
||
- `entities.py` - ForbiddenWord, BehaviorRule, GuardrailResult, InputScanResult 实体 ✅
|
||
- `services/`
|
||
- `guardrail/` - 输出护栏服务 ✅
|
||
- `__init__.py` - 模块导出
|
||
- `word_service.py` - 禁词 CRUD、命中统计、缓存
|
||
- `behavior_service.py` - 行为规则 CRUD、缓存、Prompt 注入格式化
|
||
- `input_scanner.py` - 用户输入前置检测（仅记录，不阻断）
|
||
- `output_filter.py` - LLM 输出后置过滤（mask/replace/block）
|
||
- `streaming_filter.py` - Streaming 滑动窗口检测
|
||
|
||
### Key Decisions (Why / Impact)
|
||
|
||
- decision: 三种禁词替换策略
|
||
reason: 满足不同场景的内容合规需求
|
||
impact: mask 星号替换、replace 指定文本替换、block 拦截整条回复返回兜底话术
|
||
|
||
- decision: 输入检测不阻断
|
||
reason: 用户输入包含禁词时仍需正常处理，仅记录用于监控分析
|
||
impact: InputScanner 返回 flagged 状态和匹配信息，不抛异常
|
||
|
||
- decision: Streaming 滑动窗口检测
|
||
reason: 流式输出无法预知完整内容，需要缓冲区检测跨 chunk 的禁词
|
||
impact: 维护滑动窗口 buffer（默认 50 字符，自动调整到最长禁词长度），检测到禁词后立即停止
|
||
|
||
- decision: 行为规则注入 Prompt
|
||
reason: 行为规则作为 LLM 的行为约束，不进行运行时检测
|
||
impact: BehaviorRuleService 提供 format_rules_for_prompt() 方法，追加到系统指令末尾
|
||
|
||
- decision: 内存缓存 + TTL 策略
|
||
reason: 减少数据库查询，提升过滤性能
|
||
impact: 缓存 TTL=60s，CRUD 操作时主动失效
|
||
|
||
---
|
||
|
||
## 🧾 Session History
|
||
|
||
### Session #10 (2026-02-27)
|
||
- completed:
|
||
- T14.1-T14.7 输出护栏核心功能
|
||
- 实现 ForbiddenWord 和 BehaviorRule 实体
|
||
- 实现 ForbiddenWordService（CRUD、命中统计、缓存）
|
||
- 实现 BehaviorRuleService（CRUD、缓存、Prompt 注入格式化）
|
||
- 实现 InputScanner（用户输入前置检测，仅记录不阻断）
|
||
- 实现 OutputFilter（LLM 输出后置过滤，mask/replace/block 三种策略）
|
||
- 实现 StreamingGuardrail（Streaming 滑动窗口检测）
|
||
- 实现护栏管理 API（禁词和行为规则 CRUD）
|
||
- changes:
|
||
- 新增 `app/models/entities.py` ForbiddenWord, BehaviorRule, GuardrailResult, InputScanResult 实体
|
||
- 新增 `app/services/guardrail/__init__.py` 模块导出
|
||
- 新增 `app/services/guardrail/word_service.py` 禁词服务
|
||
- 新增 `app/services/guardrail/behavior_service.py` 行为规则服务
|
||
- 新增 `app/services/guardrail/input_scanner.py` 输入扫描器
|
||
- 新增 `app/services/guardrail/output_filter.py` 输出过滤器
|
||
- 新增 `app/services/guardrail/streaming_filter.py` Streaming 过滤器
|
||
- 新增 `app/api/admin/guardrails.py` 护栏管理 API
|
||
- 更新 `app/api/admin/__init__.py` 导出新路由
|
||
- 更新 `app/main.py` 注册新路由
|
||
- 更新 `spec/ai-service/tasks.md` 标记任务完成
|
||
- notes:
|
||
- T14.8（单元测试）留到集成阶段
|
||
- 禁词检测三种策略：mask（星号替换）、replace（指定文本替换）、block（拦截返回兜底话术）
|
||
- InputScanner 仅记录命中，不阻断请求
|
||
- OutputFilter 应用 mask/replace/block 策略
|
||
- StreamingGuardrail 使用滑动窗口 buffer（默认 50 字符，自动调整）
|
||
|
||
### Session #9 (2026-02-27)
|
||
- completed:
|
||
- T11.1-T11.5 多知识库管理核心功能
|
||
- 扩展 KnowledgeBase 实体（kb_type、priority、is_enabled、doc_count）
|
||
- 实现 KnowledgeBaseService（CRUD、Collection 初始化/清理、文档计数）
|
||
- 实现知识库管理 API（POST/GET/PUT/DELETE）
|
||
- 升级 Qdrant Collection 命名（kb_{tenantId}_{kbId}，兼容旧格式）
|
||
- 修改文档上传流程（支持 kbId 参数，索引到对应 Collection）
|
||
- changes:
|
||
- 新增 `app/models/entities.py` KBType 枚举、KnowledgeBaseCreate/Update Schema
|
||
- 新增 `app/services/knowledge_base_service.py` 知识库 CRUD 服务
|
||
- 更新 `app/core/qdrant_client.py` 多知识库 Collection 管理方法
|
||
- 更新 `app/api/admin/kb.py` 知识库管理 API 和文档上传流程
|
||
- 更新 `spec/ai-service/tasks.md` 标记任务完成
|
||
- notes:
|
||
- T11.6（OptimizedRetriever 多 Collection 检索）、T11.7（kb_default 迁移）、T11.8（单元测试）留待集成阶段
|
||
- 进度文档已写入 `ai-service/docs/progress/phase11_multi_kb_progress.md`
|
||
|
||
### Session #8 (2026-02-27)
|
||
- completed:
|
||
- T12.1-T12.5 意图识别与规则引擎核心功能
|
||
- 实现 IntentRule 实体（支持关键词、正则、优先级、四种响应类型）
|
||
- 实现 IntentRuleService（CRUD、命中统计、缓存）
|
||
- 实现 IntentRouter 匹配引擎（按优先级 DESC 遍历，先关键词再正则）
|
||
- 实现规则缓存（按 tenant_id 缓存，TTL=60s，CRUD 主动失效）
|
||
- 实现意图规则管理 API（POST/GET/PUT/DELETE）
|
||
- changes:
|
||
- 新增 `app/models/entities.py` IntentRule, IntentRuleCreate, IntentRuleUpdate, IntentMatchResult 实体
|
||
- 新增 `app/services/intent/__init__.py` 模块导出
|
||
- 新增 `app/services/intent/rule_service.py` 规则服务
|
||
- 新增 `app/services/intent/router.py` 匹配引擎
|
||
- 新增 `app/api/admin/intent_rules.py` 规则管理 API
|
||
- 更新 `app/api/admin/__init__.py` 导出新路由
|
||
- 更新 `app/main.py` 注册新路由
|
||
- 更新 `spec/ai-service/tasks.md` 标记任务完成
|
||
- notes:
|
||
- T12.6（Orchestrator 集成）和 T12.7（单元测试）留待集成阶段
|
||
|
||
### Session #7 (2026-02-27)
|
||
- completed:
|
||
- T10.1-T10.8 Prompt 模板化核心功能
|
||
- 实现 PromptTemplate 和 PromptTemplateVersion 实体
|
||
- 实现 PromptTemplateService（CRUD、版本管理、发布/回滚、缓存）
|
||
- 实现 VariableResolver 变量替换引擎
|
||
- 实现 Prompt 模板管理 API（CRUD + 发布/回滚）
|
||
- changes:
|
||
- 新增 `app/models/entities.py` PromptTemplate, PromptTemplateVersion 实体
|
||
- 新增 `app/services/prompt/template_service.py` 模板服务
|
||
- 新增 `app/services/prompt/variable_resolver.py` 变量替换引擎
|
||
- 新增 `app/api/admin/prompt_templates.py` 模板管理 API
|
||
- 更新 `app/main.py` 注册新路由
|
||
- 更新 `spec/ai-service/tasks.md` 标记任务完成
|
||
- notes:
|
||
- T10.9（修改 Orchestrator）和 T10.10（单元测试）留待集成阶段
|
||
|
||
### Session #6 (2026-02-25)
|
||
- completed:
|
||
- T9.1-T9.10 租户管理与 RAG 优化功能
|
||
- 实现 Tenant 实体和租户管理 API
|
||
- 实现租户 ID 格式校验与自动创建
|
||
- 实现前端租户选择器
|
||
- 实现文档多编码支持
|
||
- 实现按行分块功能
|
||
- 实现 NomicEmbeddingProvider
|
||
- 实现多维度向量存储
|
||
- 实现 KnowledgeIndexer
|
||
- changes:
|
||
- 新增 `app/models/entities.py` Tenant 实体
|
||
- 更新 `app/core/middleware.py` 租户校验逻辑
|
||
- 新增 `app/api/admin/tenants.py` 租户管理 API
|
||
- 新增 `ai-service-admin/src/api/tenant.ts` 前端 API
|
||
- 更新 `ai-service-admin/src/App.vue` 租户选择器
|
||
- 更新 `ai-service/app/api/admin/kb.py` 多编码支持
|
||
- 新增 `app/services/embedding/nomic_provider.py`
|
||
- 新增 `app/services/retrieval/indexer.py`
|
||
- 新增 `app/services/retrieval/metadata.py`
|
||
- 新增 `app/services/retrieval/optimized_retriever.py`
|
||
|
||
---
|
||
|
||
## 🚀 Startup Guide
|
||
|
||
1. 读取本进度文档，定位当前 Phase 与 Next Action。
|
||
2. 打开并阅读 Spec References 指向的模块规范。
|
||
3. 直接执行 Next Action；遇到缺口先更新 spec 再编码。
|