docs: add ai-service provider openapi [AC-AISVC-01]
This commit is contained in:
MerCry
parent
78fec1fc8e
commit
2fdc91a54c
|
|
@ -0,0 +1,188 @@
|
||||||
|
openapi: 3.0.3
|
||||||
|
info:
|
||||||
|
title: AI Service API
|
||||||
|
description: |
|
||||||
|
Python AI 服务接口契约。
|
||||||
|
|
||||||
|
本文件定义主框架对 AI 服务的接口需求（Consumer-First）。
|
||||||
|
由主框架作为调用方，Python AI 服务作为提供方实现。
|
||||||
|
version: 1.0.0
|
||||||
|
x-contract-level: L0
|
||||||
|
x-consumer: "java-main-framework"
|
||||||
|
x-provider: "python-ai-service"
|
||||||
|
|
||||||
|
servers:
|
||||||
|
- url: http://ai-service:8080
|
||||||
|
description: AI 服务地址
|
||||||
|
|
||||||
|
paths:
|
||||||
|
/ai/chat:
|
||||||
|
post:
|
||||||
|
operationId: generateReply
|
||||||
|
summary: 生成 AI 回复
|
||||||
|
description: |
|
||||||
|
根据用户消息和会话历史生成 AI 回复。
|
||||||
|
|
||||||
|
覆盖验收标准：
|
||||||
|
- 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
|
||||||
|
requestBody:
|
||||||
|
required: true
|
||||||
|
content:
|
||||||
|
application/json:
|
||||||
|
schema:
|
||||||
|
$ref: '#/components/schemas/ChatRequest'
|
||||||
|
example:
|
||||||
|
sessionId: "kf_001_wx123456_1708765432000"
|
||||||
|
currentMessage: "我想了解产品价格"
|
||||||
|
channelType: "wechat"
|
||||||
|
responses:
|
||||||
|
'200':
|
||||||
|
description: 成功生成回复
|
||||||
|
content:
|
||||||
|
application/json:
|
||||||
|
schema:
|
||||||
|
$ref: '#/components/schemas/ChatResponse'
|
||||||
|
example:
|
||||||
|
reply: "您好，我们的产品价格根据套餐不同有所差异。"
|
||||||
|
confidence: 0.92
|
||||||
|
shouldTransfer: false
|
||||||
|
'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: 服务不健康
|
||||||
|
|
||||||
|
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
|
||||||
|
|
@ -0,0 +1,248 @@
|
||||||
|
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.0.0
|
||||||
|
x-contract-level: L0
|
||||||
|
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: 健康检查
|
||||||
|
|
||||||
|
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: 服务不健康
|
||||||
|
|
||||||
|
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
|
||||||
Loading…
Reference in New Issue