ai-robot-core/spec/ai-service-admin/openapi.deps.yaml

openapi: 3.1.0
info:
  title: "AI Service Admin Dependencies"
  description: "ai-service-admin 模块依赖的外部 API 契约（Consumer 需求侧）"
  version: "0.3.0"
  x-contract-level: L1

servers:
  - url: http://localhost:8000
    description: 本地开发服务器

paths:
  /admin/embedding/providers:
    get:
      operationId: listEmbeddingProviders
      summary: 获取可用的嵌入模型提供者列表
      tags:
        - Embedding Management
      parameters:
        - name: X-Tenant-Id
          in: header
          required: true
          schema:
            type: string
      responses:
        '200':
          description: 成功返回提供者列表
          content:
            application/json:
              schema:
                type: object
                properties:
                  providers:
                    type: array
                    items:
                      $ref: '#/components/schemas/EmbeddingProviderInfo'

  /admin/embedding/config:
    get:
      operationId: getEmbeddingConfig
      summary: 获取当前嵌入模型配置
      tags:
        - Embedding Management
      parameters:
        - name: X-Tenant-Id
          in: header
          required: true
          schema:
            type: string
      responses:
        '200':
          description: 成功返回当前配置
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EmbeddingConfig'
    put:
      operationId: updateEmbeddingConfig
      summary: 更新嵌入模型配置
      tags:
        - Embedding Management
      parameters:
        - name: X-Tenant-Id
          in: header
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EmbeddingConfigUpdate'
      responses:
        '200':
          description: 配置更新成功
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  message:
                    type: string

  /admin/embedding/test:
    post:
      operationId: testEmbedding
      summary: 测试嵌入模型连接
      tags:
        - Embedding Management
      parameters:
        - name: X-Tenant-Id
          in: header
          required: true
          schema:
            type: string
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
              properties:
                test_text:
                  type: string
                  description: 测试文本（可选）
                config:
                  $ref: '#/components/schemas/EmbeddingConfigUpdate'
      responses:
        '200':
          description: 测试成功
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EmbeddingTestResult'

  /admin/embedding/formats:
    get:
      operationId: getSupportedFormats
      summary: 获取支持的文档格式列表
      tags:
        - Embedding Management
      parameters:
        - name: X-Tenant-Id
          in: header
          required: true
          schema:
            type: string
      responses:
        '200':
          description: 成功返回支持格式列表
          content:
            application/json:
              schema:
                type: object
                properties:
                  formats:
                    type: array
                    items:
                      $ref: '#/components/schemas/DocumentFormat'

  /admin/llm/providers:
    get:
      operationId: listLLMProviders
      summary: 获取可用的 LLM 提供者列表
      tags:
        - LLM Management
      parameters:
        - name: X-Tenant-Id
          in: header
          required: true
          schema:
            type: string
      responses:
        '200':
          description: 成功返回提供者列表
          content:
            application/json:
              schema:
                type: object
                properties:
                  providers:
                    type: array
                    items:
                      $ref: '#/components/schemas/LLMProviderInfo'

  /admin/llm/config:
    get:
      operationId: getLLMConfig
      summary: 获取当前 LLM 配置
      tags:
        - LLM Management
      parameters:
        - name: X-Tenant-Id
          in: header
          required: true
          schema:
            type: string
      responses:
        '200':
          description: 成功返回当前配置
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LLMConfig'
    put:
      operationId: updateLLMConfig
      summary: 更新 LLM 配置
      tags:
        - LLM Management
      parameters:
        - name: X-Tenant-Id
          in: header
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/LLMConfigUpdate'
      responses:
        '200':
          description: 配置更新成功
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  message:
                    type: string

  /admin/llm/test:
    post:
      operationId: testLLM
      summary: 测试 LLM 连接
      tags:
        - LLM Management
      parameters:
        - name: X-Tenant-Id
          in: header
          required: true
          schema:
            type: string
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
              properties:
                test_prompt:
                  type: string
                  description: 测试提示词（可选）
                  example: "你好，请简单介绍一下自己。"
                config:
                  $ref: '#/components/schemas/LLMConfigUpdate'
      responses:
        '200':
          description: 测试成功
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LLMTestResult'

  /admin/rag/experiments/run:
    post:
      operationId: runRagExperiment
      summary: 运行 RAG 实验（含 AI 输出）
      tags:
        - RAG Lab
      parameters:
        - name: X-Tenant-Id
          in: header
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RagExperimentRequest'
      responses:
        '200':
          description: 实验完成
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RagExperimentResult'

  /admin/rag/experiments/stream:
    post:
      operationId: runRagExperimentStream
      summary: 运行 RAG 实验（流式输出）
      tags:
        - RAG Lab
      parameters:
        - name: X-Tenant-Id
          in: header
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RagExperimentRequest'
      responses:
        '200':
          description: SSE 流式输出
          content:
            text/event-stream:
              schema:
                type: string

components:
  schemas:
    EmbeddingProviderInfo:
      type: object
      required:
        - name
        - display_name
        - config_schema
      properties:
        name:
          type: string
          description: 提供者唯一标识
          example: "ollama"
        display_name:
          type: string
          description: 提供者显示名称
          example: "Ollama 本地模型"
        description:
          type: string
          description: 提供者描述
          example: "使用 Ollama 运行的本地嵌入模型"
        config_schema:
          type: object
          description: 配置参数定义（JSON Schema 格式）
          additionalProperties: true

    EmbeddingConfig:
      type: object
      required:
        - provider
        - config
      properties:
        provider:
          type: string
          description: 当前激活的提供者
          example: "ollama"
        config:
          type: object
          description: 提供者配置参数
          additionalProperties: true
        updated_at:
          type: string
          format: date-time
          description: 配置最后更新时间

    EmbeddingConfigUpdate:
      type: object
      required:
        - provider
      properties:
        provider:
          type: string
          description: 提供者标识
          example: "ollama"
        config:
          type: object
          description: 提供者配置参数
          additionalProperties: true

    EmbeddingTestResult:
      type: object
      required:
        - success
        - dimension
      properties:
        success:
          type: boolean
          description: 测试是否成功
        dimension:
          type: integer
          description: 返回的向量维度
          example: 768
        latency_ms:
          type: number
          description: 响应延迟（毫秒）
          example: 125.5
        message:
          type: string
          description: 测试结果消息
          example: "连接成功，向量维度: 768"
        error:
          type: string
          description: 错误信息（失败时）
          example: "连接超时"

    DocumentFormat:
      type: object
      required:
        - extension
        - name
      properties:
        extension:
          type: string
          description: 文件扩展名
          example: ".pdf"
        name:
          type: string
          description: 格式名称
          example: "PDF 文档"
        description:
          type: string
          description: 格式描述
          example: "使用 PyMuPDF 解析 PDF 文档"

    LLMProviderInfo:
      type: object
      required:
        - name
        - display_name
        - config_schema
      properties:
        name:
          type: string
          description: 提供者唯一标识
          example: "openai"
        display_name:
          type: string
          description: 提供者显示名称
          example: "OpenAI"
        description:
          type: string
          description: 提供者描述
          example: "OpenAI GPT 系列模型"
        config_schema:
          type: object
          description: 配置参数定义（JSON Schema 格式）
          additionalProperties: true

    LLMConfig:
      type: object
      required:
        - provider
        - config
      properties:
        provider:
          type: string
          description: 当前激活的提供者
          example: "openai"
        config:
          type: object
          description: 提供者配置参数
          additionalProperties: true
          example:
            api_key: "sk-xxx"
            base_url: "https://api.openai.com/v1"
            model: "gpt-4o-mini"
        updated_at:
          type: string
          format: date-time
          description: 配置最后更新时间

    LLMConfigUpdate:
      type: object
      required:
        - provider
      properties:
        provider:
          type: string
          description: 提供者标识
          example: "openai"
        config:
          type: object
          description: 提供者配置参数
          additionalProperties: true

    LLMTestResult:
      type: object
      required:
        - success
      properties:
        success:
          type: boolean
          description: 测试是否成功
        response:
          type: string
          description: LLM 响应内容
          example: "你好！我是一个 AI 助手..."
        latency_ms:
          type: number
          description: 响应延迟（毫秒）
          example: 1250.5
        prompt_tokens:
          type: integer
          description: 输入 Token 数
          example: 15
        completion_tokens:
          type: integer
          description: 输出 Token 数
          example: 50
        total_tokens:
          type: integer
          description: 总 Token 数
          example: 65
        message:
          type: string
          description: 测试结果消息
          example: "连接成功"
        error:
          type: string
          description: 错误信息（失败时）
          example: "API Key 无效"

    RagExperimentRequest:
      type: object
      required:
        - query
      properties:
        query:
          type: string
          description: 查询文本
          example: "什么是 RAG？"
        kb_ids:
          type: array
          items:
            type: string
          description: 知识库 ID 列表
        top_k:
          type: integer
          description: 检索数量
          default: 5
        score_threshold:
          type: number
          description: 相似度阈值
          default: 0.5
        llm_provider:
          type: string
          description: 指定 LLM 提供者（可选）
          example: "openai"
        generate_response:
          type: boolean
          description: 是否生成 AI 回复
          default: true

    RagExperimentResult:
      type: object
      properties:
        query:
          type: string
          description: 原始查询
        retrieval_results:
          type: array
          items:
            $ref: '#/components/schemas/RetrievalResult'
        final_prompt:
          type: string
          description: 最终拼接的 Prompt
        ai_response:
          $ref: '#/components/schemas/AIResponse'
        total_latency_ms:
          type: number
          description: 总耗时（毫秒）

    RetrievalResult:
      type: object
      properties:
        content:
          type: string
          description: 检索到的内容
        score:
          type: number
          description: 相似度分数
        source:
          type: string
          description: 来源文档
        metadata:
          type: object
          additionalProperties: true
          description: 元数据

    AIResponse:
      type: object
      properties:
        content:
          type: string
          description: AI 回复内容
        prompt_tokens:
          type: integer
          description: 输入 Token 数
        completion_tokens:
          type: integer
          description: 输出 Token 数
        total_tokens:
          type: integer
          description: 总 Token 数
        latency_ms:
          type: number
          description: 生成耗时（毫秒）
        model:
          type: string
          description: 使用的模型