ai-robot-core/docs/progress/ai-service-progress.md

ai-service - Progress

---

📋 Context

• module: ai-service
• feature: AISVC (Python AI 中台)
• status: ✅ 已完成

---

🔗 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)

• Phase 1: 基础设施（FastAPI 框架与多租户基础） (100%) ✅
• Phase 2: 存储与检索实现（Memory & Retrieval） (100%) ✅
• Phase 3: 核心编排（Orchestrator & LLM Adapter） (100%) ✅
• Phase 4: 流式响应（SSE 实现与状态机） (100%) ✅
• Phase 5: 集成与冒烟测试（Quality Assurance） (100%) ✅
• Phase 6: 前后端联调真实对接 (100%) ✅
• Phase 7: 嵌入模型可插拔与文档解析 (100%) ✅
• Phase 8: LLM 配置与 RAG 调试输出 (100%) ✅
• Phase 9: 租户管理与 RAG 优化 (100%) ✅

---

🔄 Current Phase

Goal

Phase 9 已完成！项目进入稳定迭代阶段。

Completed Tasks (Phase 9)

• T9.1 实现 Tenant 实体：定义租户数据模型 [AC-AISVC-10] ✅
• T9.2 实现租户 ID 格式校验：name@ash@year 格式验证 [AC-AISVC-10, AC-AISVC-12] ✅
• T9.3 实现租户自动创建：请求时自动创建不存在的租户 [AC-AISVC-10] ✅
• T9.4 实现 GET /admin/tenants API：返回租户列表 [AC-AISVC-10] ✅
• T9.5 前端租户选择器：实现租户切换功能 [AC-ASA-01] ✅
• T9.6 文档多编码支持：支持 UTF-8、GBK、GB2312 等编码解码 [AC-AISVC-21] ✅
• T9.7 按行分块功能：实现 chunk_text_by_lines 函数 [AC-AISVC-22] ✅
• T9.8 实现 NomicEmbeddingProvider：支持多维度向量 [AC-AISVC-29] ✅
• T9.9 实现多向量存储：支持 full/256/512 三种维度 [AC-AISVC-16] ✅
• T9.10 实现 KnowledgeIndexer：优化的知识库索引服务 [AC-AISVC-22] ✅

---

🏗️ Technical Context

Module Structure

• ai-service/
  • app/
    • api/ - FastAPI 路由层
      • admin/tenants.py - 租户管理 API ✅
    • core/ - 配置、异常、中间件、SSE
      • middleware.py - 租户 ID 格式校验与自动创建 ✅
    • models/ - Pydantic 模型和 SQLModel 实体
      • entities.py - Tenant 实体 ✅
    • services/
      • embedding/nomic_provider.py - Nomic 嵌入提供者 ✅
      • retrieval/ - 检索层
        • indexer.py - 知识库索引服务 ✅
        • metadata.py - 元数据模型 ✅
        • optimized_retriever.py - 优化检索器 ✅
  • tests/ - 单元测试

Key Decisions (Why / Impact)

• decision: 租户 ID 格式采用 name@ash@year 格式 reason: 便于解析和展示租户信息 impact: 中间件自动校验格式并解析

• decision: 租户自动创建策略 reason: 简化租户管理流程，无需预先创建 impact: 首次请求时自动创建租户记录

• decision: 多维度向量存储（full/256/512） reason: 支持不同检索场景的性能优化 impact: Qdrant 使用 named vector 存储

• decision: 文档多编码支持 reason: 兼容中文文档的各种编码格式 impact: 按优先级尝试多种编码解码

---

🧾 Session History

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
• commits:
  • docs: 更新任务清单，添加 Phase 9 租户管理与 RAG 优化任务 [AC-AISVC-10, AC-ASA-01]
  • feat: 实现租户管理功能，支持租户ID格式校验与自动创建 [AC-AISVC-10, AC-AISVC-12, AC-ASA-01]
  • feat: 文档索引优化，支持多编码解码和按行分块 [AC-AISVC-21, AC-AISVC-22]
  • feat: RAG 检索优化，实现多维度向量存储和 Nomic 嵌入提供者 [AC-AISVC-16, AC-AISVC-29]
  • feat: RAG 配置优化与检索日志增强 [AC-AISVC-16, AC-AISVC-17]

---

🚀 Startup Guide

1. 读取本进度文档，定位当前 Phase 与 Next Action。
2. 打开并阅读 Spec References 指向的模块规范。
3. 直接执行 Next Action；遇到缺口先更新 spec 再编码。