openapi: 3.0.3 info: title: AI Service API description: | Python AI 服务对外提供的接口契约（Provider）。 目标：100% 覆盖并对齐 Java 端 Consumer-First 依赖契约 `java/openapi.deps.yaml`。 - 路径与方法必须一致 - non-streaming JSON 响应 schema 必须一致（reply/confidence/shouldTransfer 等） 额外扩展：支持 SSE 流式输出（Accept: text/event-stream）。 version: 1.1.0 x-contract-level: L2 x-provider: "python-ai-service" x-consumer: "java-main-framework" servers: - url: http://ai-service:8080 description: AI 服务地址 tags: - name: AI Chat description: 对话生成 - name: Health description: 健康检查 - name: Embedding Management description: 嵌入模型管理 paths: /ai/chat: post: operationId: generateReply summary: 生成 AI 回复 description: | 根据用户消息和会话历史生成 AI 回复。 non-streaming：返回 application/json（ChatResponse）。 streaming：当请求头包含 `Accept: text/event-stream` 时，以 SSE 推送事件流。 覆盖验收标准（来自 Java 侧契约描述）： - AC-MCA-04: 主框架通过 HTTP POST 调用 AI 服务 - AC-MCA-05: 响应包含 reply、confidence、shouldTransfer 字段 - AC-MCA-06: AI 服务不可用时的降级处理（主框架侧实现） - AC-MCA-07: 超时处理（主框架侧实现） tags: - AI Chat x-requirements: - AC-MCA-04 - AC-MCA-04-REQ - AC-MCA-04-OPT - AC-MCA-05 - AC-MCA-06 - AC-MCA-07 parameters: - name: X-Tenant-Id in: header required: true description: 租户ID（多租户隔离必填，便于网关/拦截器统一处理） schema: type: string - name: Accept in: header required: false description: | 内容协商。 - 设置为 text/event-stream 时返回 SSE 事件流 - 其他情况返回 application/json schema: type: string requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/ChatRequest' example: sessionId: "kf_001_wx123456_1708765432000" currentMessage: "我想了解产品价格" channelType: "wechat" metadata: channelUserId: "wx123456" extra: "..." responses: '200': description: | 成功生成回复。 注意： - non-streaming：响应 Content-Type 为 application/json - streaming：当请求头 Accept: text/event-stream 时，服务端可返回 text/event-stream（见下方 200 的第二种 content 描述） content: application/json: schema: $ref: '#/components/schemas/ChatResponse' example: reply: "您好，我们的产品价格根据套餐不同有所差异。" confidence: 0.92 shouldTransfer: false text/event-stream: schema: type: string description: | SSE 事件流（按行文本）。事件模型： 1) event: message - data: {"delta": "..."} - 返回时机：模型生成过程中多次发送，用于增量渲染。 2) event: final - data: ChatResponse（完整结构化结果，字段至少包含 reply/confidence/shouldTransfer） - 返回时机：生成结束时发送一次，随后关闭连接。 3) event: error - data: ErrorResponse（结构化错误，至少 code/message，可含 details） - 返回时机：发生错误时发送一次，随后关闭连接。 示例（片段）： event: message\n data: {"delta":"您好，"}\n event: final\n data: {"reply":"...","confidence":0.9,"shouldTransfer":false}\n '400': description: 请求参数错误 content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '500': description: 服务内部错误 content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '503': description: 服务不可用 content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' /ai/health: get: operationId: healthCheck summary: 健康检查 description: 检查 AI 服务是否正常运行 tags: - Health responses: '200': description: 服务正常 content: application/json: schema: type: object properties: status: type: string '503': description: 服务不健康 /admin/embedding/providers: get: operationId: listEmbeddingProviders summary: 获取可用的嵌入模型提供者列表 description: | 返回所有已注册的嵌入模型提供者及其配置参数定义。 覆盖验收标准： - AC-AISVC-38: 返回所有已注册的提供者列表及其配置参数定义 tags: - Embedding Management x-requirements: - AC-AISVC-38 parameters: - name: X-Tenant-Id in: header required: true description: 租户ID schema: type: string responses: '200': description: 成功返回提供者列表 content: application/json: schema: type: object properties: providers: type: array items: $ref: '#/components/schemas/EmbeddingProviderInfo' '500': description: 服务内部错误 content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' /admin/embedding/config: get: operationId: getEmbeddingConfig summary: 获取当前嵌入模型配置 description: | 返回当前激活的嵌入模型提供者及其参数配置。 覆盖验收标准： - AC-AISVC-39: 返回当前激活的提供者及其参数配置 tags: - Embedding Management x-requirements: - AC-AISVC-39 parameters: - name: X-Tenant-Id in: header required: true description: 租户ID schema: type: string responses: '200': description: 成功返回当前配置 content: application/json: schema: $ref: '#/components/schemas/EmbeddingConfig' '500': description: 服务内部错误 content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' put: operationId: updateEmbeddingConfig summary: 更新嵌入模型配置 description: | 更新嵌入模型配置，支持热更新（无需重启服务）。 覆盖验收标准： - AC-AISVC-40: 验证配置有效性，更新配置并返回成功状态 - AC-AISVC-31: 支持热更新 tags: - Embedding Management x-requirements: - AC-AISVC-40 - AC-AISVC-31 parameters: - name: X-Tenant-Id in: header required: true description: 租户ID schema: type: string requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/EmbeddingConfigUpdate' example: provider: "ollama" config: base_url: "http://localhost:11434" model: "nomic-embed-text" dimension: 768 responses: '200': description: 配置更新成功 content: application/json: schema: type: object properties: success: type: boolean message: type: string '400': description: 配置参数无效 content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '500': description: 服务内部错误 content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' /admin/embedding/test: post: operationId: testEmbedding summary: 测试嵌入模型连接 description: | 调用嵌入模型生成测试向量，返回连接状态和向量维度信息。 覆盖验收标准： - AC-AISVC-41: 调用嵌入模型生成测试向量，返回连接状态和向量维度信息 tags: - Embedding Management x-requirements: - AC-AISVC-41 parameters: - name: X-Tenant-Id in: header required: true description: 租户ID schema: type: string requestBody: required: false content: application/json: schema: type: object properties: test_text: type: string description: 测试文本（可选，默认使用固定测试文本） example: "这是一个测试文本" config: $ref: '#/components/schemas/EmbeddingConfigUpdate' description: 测试配置（可选，不传则使用当前配置） responses: '200': description: 测试成功 content: application/json: schema: $ref: '#/components/schemas/EmbeddingTestResult' '400': description: 配置参数无效 content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '500': description: 连接测试失败 content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' components: schemas: ChatRequest: type: object required: - sessionId - currentMessage - channelType properties: sessionId: type: string description: 会话ID（AC-MCA-04-REQ 必填） currentMessage: type: string description: 当前用户消息（AC-MCA-04-REQ 必填） channelType: type: string description: 渠道类型（AC-MCA-04-REQ 必填） enum: - wechat - douyin - jd history: type: array description: 历史消息列表（AC-MCA-04-OPT 可选） items: $ref: '#/components/schemas/ChatMessage' metadata: type: object description: 扩展元数据（AC-MCA-04-OPT 可选） additionalProperties: true ChatMessage: type: object required: - role - content properties: role: type: string enum: - user - assistant content: type: string ChatResponse: type: object required: - reply - confidence - shouldTransfer properties: reply: type: string description: AI 回复内容（AC-MCA-05 必填） confidence: type: number format: double description: 置信度评分 0.0-1.0（AC-MCA-05 必填） shouldTransfer: type: boolean description: 是否建议转人工（AC-MCA-05 必填） transferReason: type: string description: 转人工原因（可选） metadata: type: object description: 响应元数据（可选） additionalProperties: true ErrorResponse: type: object required: - code - message properties: code: type: string description: 错误代码 message: type: string description: 错误消息 details: type: array description: 详细错误信息（可选） items: type: object additionalProperties: true EmbeddingProviderInfo: type: object description: 嵌入模型提供者信息 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 example: base_url: type: "string" description: "Ollama API 地址" default: "http://localhost:11434" model: type: "string" description: "模型名称" default: "nomic-embed-text" dimension: type: "integer" description: "向量维度" default: 768 EmbeddingConfig: type: object description: 当前嵌入模型配置 required: - provider - config properties: provider: type: string description: 当前激活的提供者 example: "ollama" config: type: object description: 提供者配置参数 additionalProperties: true example: base_url: "http://localhost:11434" model: "nomic-embed-text" dimension: 768 updated_at: type: string format: date-time description: 配置最后更新时间 EmbeddingConfigUpdate: type: object description: 嵌入模型配置更新请求 required: - provider properties: provider: type: string description: 提供者标识 example: "ollama" config: type: object description: 提供者配置参数 additionalProperties: true EmbeddingTestResult: type: object description: 嵌入模型测试结果 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: "连接超时"