189 lines
5.0 KiB
YAML
189 lines
5.0 KiB
YAML
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
|