MerCry
/
ai-robot-core
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
ai-robot-core/spec/ai-service-admin/scope.md

8.8 KiB
Raw Blame History

module title status version owners last_updated methodology
ai-service-admin AI 中台管理界面（ai-service-admin）— Scoping（定界）结果 draft 0.1.0
product
frontend
backend
2026-02-24
spec-driven
api-first

AI 中台管理界面（ai-service-admin）— Scoping（定界）结果

本文档为“规范驱动 + 接口先行”的第 0 阶段产出：模块边界澄清 + 依赖接口盘点（Consumer-First）。

输出完成后停止，等待确认；在确认前不进入 requirements/OpenAPI/Design/Tasks 的正式编写。

1) 模块职责（Module Responsibilities）

1.1 模块定位

ai-service-admin 是一个独立前端管理模块，面向运营/管理员/租户管理员，用于管理 AI 中台的知识库资产、租户级配置、RAG 调试与全局会话观测。

1.2 包含（In Scope）

必须覆盖以下能力（以管理与观测为主）：

  1. 知识库上传/索引管理

    • 数据源上传（文件/文本/URL 等，具体形态由后续 requirements 细化）
    • 数据源状态查看、重试、删除/下线
    • 索引构建（触发/进度/失败原因）与文档分片/向量化相关的可观测信息（仅展示，不实现算法）
    • 基础检索配置（如 topK、召回阈值、chunk 策略等）：以“配置项编辑 + 生效范围”呈现

  2. 租户级 Prompt 模板配置

    • 租户维度的 Prompt 模板 CRUD、版本管理（草案/发布）、回滚
    • 模板与使用场景（如：RAG 问答、工具调用、摘要等）的绑定（场景枚举由后端定义）
    • 变量占位符与校验提示（前端校验为体验增强，最终以后端校验为准）

  3. RAG 检索效果实验室（调试窗）

    • 输入问题 → 触发“检索/重排/上下文构造”调试链路
    • 展示：召回文档列表（含得分/来源/片段）、重排结果、最终上下文、以及关键日志/耗时
    • 支持对比实验（如不同检索参数、不同 prompt 版本）
    • 支持保存/复用实验配置与结果快照（用于回归对比）

  4. 全局会话监控

    • 多租户维度的会话列表、筛选（时间、租户、用户标识、会话状态、模型/渠道等）
    • 查看单次会话详情：消息流、检索命中、工具调用、错误栈/错误码、耗时
    • 基础统计：会话量、失败率、平均耗时、Top 知识库/Top Prompt 版本使用情况（指标范围后续细化）

1.3 不包含（Out of Scope）

明确不在本模块实现范围内：

  • 具体 AI 推理逻辑（由 ai-service 负责），包括但不限于：LLM 调用、embedding 计算、rerank 算法、提示词编排执行引擎本体。
  • 用户侧聊天界面（由 ai-robot 负责），即面向终端用户的对话交互 UI。
  • 底层存储/索引实现（向量库、全文检索、对象存储等）与运维部署策略。

1.4 边界接口原则

  • ai-service-admin 只作为 Consumer（调用方） 消费 Python 后端（ai-service）提供的“管理类/观测类 API”。
  • 所有“调试/实验”动作也通过管理 API 触发，前端不直接连接向量库或模型。

2) 技术栈建议（Tech Stack Recommendation）

2.1 选型建议

优先推荐：Vue 3 + Element Plus（与 RuoYi-Vue 生态对齐）。 备选：React（若团队已有成熟 React 组件体系与工程基座）。

2.2 选择理由（面向本模块）

  • RuoYi-Vue 管理后台形态与 Element Plus 组件库天然匹配（表格/表单/弹窗/权限路由）。
  • 本模块以“配置管理 + 列表筛选 + 详情查看 + 调试面板”交互为主，Element Plus 现成组件覆盖度高。

2.3 工程与基础能力（建议纳入后续 design）

  • 多租户与权限：建议前端采用路由级权限 + 按钮级权限（能力来源于后端返回的权限集）。
  • 国际化：可选（若需要多语言运营）。
  • 可观测性：前端埋点/日志仅做体验与错误上报；业务日志以服务端为准。

3) 依赖接口清单（Consumer-First，管理类接口草案）

说明：以下为 ai-service-admin 作为调用方所需的最小管理接口能力清单（草案）。

  • 路径以 /admin/* 为主。
  • 最终将以 ai-service 新增的 openapi.admin.yaml 固化。
  • 这里先列“能力/端点草案”，不写具体 schema，以便先对齐边界。

3.1 认证与通用能力

  • GET /admin/me：获取当前登录信息（含租户、角色、权限点）
  • GET /admin/tenants：租户列表（平台管理员）
  • GET /admin/enums：获取前端需要的枚举/常量（场景枚举、状态枚举、错误码映射等）

3.2 知识库（KB）管理：/admin/kb/*

  • GET /admin/kb/spaces：知识空间/知识库列表（按租户）

  • POST /admin/kb/spaces：创建知识空间/知识库

  • GET /admin/kb/spaces/{kbId}：知识库详情（含统计/配置摘要）

  • PATCH /admin/kb/spaces/{kbId}：更新知识库元信息/配置

  • DELETE /admin/kb/spaces/{kbId}：删除/下线知识库

  • GET /admin/kb/documents：文档列表（支持 kbId、状态、时间、来源筛选）

  • POST /admin/kb/documents：上传/导入文档（multipart 或任务式导入）

  • GET /admin/kb/documents/{docId}：文档详情（含分片/索引状态）

  • DELETE /admin/kb/documents/{docId}：删除文档

  • POST /admin/kb/index/jobs：触发索引构建/重建（kbId/docId 维度）

  • GET /admin/kb/index/jobs：索引任务列表（状态/时间筛选）

  • GET /admin/kb/index/jobs/{jobId}：索引任务详情（进度、失败原因、日志摘要）

  • POST /admin/kb/index/jobs/{jobId}/retry：失败任务重试

  • POST /admin/kb/index/jobs/{jobId}/cancel：取消任务（若支持）

  • GET /admin/kb/search/config：读取检索参数默认配置（租户级/KB 级）

  • PUT /admin/kb/search/config：更新检索参数默认配置

3.3 Prompt 模板（租户级）配置：/admin/config/*

  • GET /admin/config/prompt-templates：模板列表（支持场景筛选）

  • POST /admin/config/prompt-templates：创建模板（草案）

  • GET /admin/config/prompt-templates/{tplId}：模板详情（含版本历史）

  • PATCH /admin/config/prompt-templates/{tplId}：更新模板（草案编辑）

  • POST /admin/config/prompt-templates/{tplId}/publish：发布某版本

  • POST /admin/config/prompt-templates/{tplId}/rollback：回滚到指定版本

  • DELETE /admin/config/prompt-templates/{tplId}：删除模板

  • GET /admin/config/prompt-variables：可用变量/内置函数清单（用于编辑器提示）

3.4 RAG 检索效果实验室（调试）：/admin/rag/*

  • POST /admin/rag/experiments/run：运行一次 RAG 调试实验（输入 query + 参数集 + 可选 kbId/promptVersion）

  • GET /admin/rag/experiments：实验记录列表（按租户/操作者/时间）

  • GET /admin/rag/experiments/{expId}：实验详情（召回、重排、上下文、日志、耗时）

  • POST /admin/rag/experiments/{expId}/clone：复制实验为新草案

  • DELETE /admin/rag/experiments/{expId}：删除实验记录

  • GET /admin/rag/diagnostics/samples：获取预置样例（用于快速回归）

3.5 全局会话监控：/admin/sessions/*

  • GET /admin/sessions：会话列表（多维筛选）

  • GET /admin/sessions/{sessionId}：会话详情（消息流、检索命中、工具调用、错误、耗时）

  • GET /admin/sessions/stats/overview：概览统计（时间范围 + 租户维度）

  • GET /admin/sessions/stats/top：Top 指标（Top KB / Top Prompt / Top 错误码等）

3.6 审计与运维（可选但常见）

  • GET /admin/audit/logs：管理操作审计日志
  • GET /admin/system/health：服务健康/版本信息（用于后台页脚或诊断）

3.7 统一错误模型（约定）

  • 所有 /admin/* 接口建议返回统一错误结构（如 code, message, requestId, details[]），以支持后台调试与问题定位。

4) 产出物计划（Artifacts Plan）

按方法论，本模块后续应产出 4 类核心工件；本次 Scoping 仅做计划，不生成内容（等待确认）。

  1. spec/ai-service-admin/requirements.md

    • 管理后台的用户故事与验收标准（EARS）
    • Scope/Dependencies/Traceability

  2. spec/ai-service/openapi.admin.yaml（在 ai-service 下新增）

    • 作为 ai-service 的 admin provider 契约（面向本后台）
    • 标记 info.x-contract-level，并对关键 operationId 提供 L1/L2 所需字段

  3. spec/ai-service-admin/design.md

    • 前端信息架构（IA）：菜单/页面/路由/权限点
    • 状态管理、缓存策略、分页/筛选模式
    • 调试实验室的交互与可观测性设计
    • 错误处理与追踪（requestId）

  4. spec/ai-service-admin/tasks.md

    • 按页面/能力拆分的原子任务（含与 AC 的映射）
    • 并行策略：基于 admin OpenAPI 生成 Mock/SDK