ai-robot-core/AI中台对接文档.md

AI 中台对接文档

1. 概述

本文档描述 Python AI 中台对渠道侧（Java 主框架）暴露的 HTTP 接口规范，用于智能客服对话生成和服务健康检查。

1.1 服务信息

• 服务名称: AI Service (Python AI 中台)
• 服务地址: http://ai-service:8080
• 协议: HTTP/1.1
• 数据格式: JSON / SSE (Server-Sent Events)
• 字符编码: UTF-8
• 契约版本: v1.1.0

1.2 核心能力

• ✅ 智能对话生成（基于 LLM + RAG）
• ✅ 多租户隔离（基于 X-Tenant-Id）
• ✅ 会话上下文管理（基于 sessionId）
• ✅ 流式/非流式双模式输出
• ✅ 置信度评估与转人工建议
• ✅ 服务健康检查

---

2. 认证与租户隔离

2.1 API Key 认证（必填）

所有接口请求（除健康检查外）必须在 HTTP Header 中携带 API Key：

X-API-Key: <your_api_key>

说明：

• API Key 用于身份认证和访问控制
• 缺失或无效的 API Key 将返回 401 Unauthorized
• API Key 由 AI 中台管理员分配，请妥善保管
• 以下路径无需 API Key：/health、/ai/health、/docs

2.2 租户标识（必填）

所有接口请求必须在 HTTP Header 中携带租户 ID：

X-Tenant-Id: <tenant_id>

租户 ID 格式规范：name@ash@year

示例：

• szmp@ash@2026 - 深圳某项目 2026 年
• abc123@ash@2025 - ABC 项目 2025 年

说明：

• 租户 ID 用于数据隔离（知识库、会话历史、配置等）
• 缺失或格式错误的租户 ID 将返回 400 Bad Request
• 不同租户的数据完全隔离，不可跨租户访问
• 租户不存在时会自动创建

---

3. 接口列表

接口路径	方法	功能	响应模式
/ai/chat	POST	生成 AI 回复	JSON / SSE
/ai/health	GET	健康检查	JSON

---

4. 接口详细说明

4.1 生成 AI 回复

接口路径: POST /ai/chat

功能描述: 根据用户消息和会话历史生成 AI 回复，支持 RAG 检索增强、上下文管理、置信度评估。

4.1.1 请求参数

Headers:

Content-Type: application/json
X-API-Key: <your_api_key>
X-Tenant-Id: <tenant_id>
Accept: application/json  # 或 text/event-stream（流式输出）

Body (JSON):

字段	类型	必填	说明
sessionId	string	✅	会话 ID，用于关联同一会话的对话历史
currentMessage	string	✅	当前用户消息内容
channelType	string	✅	渠道类型，枚举值：wechat、douyin、jd
history	array	❌	历史消息列表（可选，AI 中台会自动管理会话历史）
metadata	object	❌	扩展元数据（可选）

history 数组元素结构:

{
  "role": "user | assistant",
  "content": "消息内容"
}

请求示例:

{
  "sessionId": "kf_001_wx123456_1708765432000",
  "currentMessage": "我想了解产品价格",
  "channelType": "wechat",
  "metadata": {
    "channelUserId": "wx123456",
    "extra": "..."
  }
}

4.1.2 响应格式

模式 1: JSON 响应（非流式）

状态码: 200 OK

响应体:

{
  "reply": "您好，我们的产品价格根据套餐不同有所差异...",
  "confidence": 0.92,
  "shouldTransfer": false,
  "transferReason": null,
  "metadata": {
    "retrieval_count": 3,
    "rag_enabled": true
  }
}

字段说明:

字段	类型	必填	说明
reply	string	✅	AI 生成的回复内容
confidence	number	✅	置信度评分（0.0-1.0），越高表示回答越可靠
shouldTransfer	boolean	✅	是否建议转人工（true=建议转人工）
transferReason	string	❌	转人工原因（可选）
metadata	object	❌	响应元数据（可选）

模式 2: SSE 流式响应

触发条件: 请求头包含 Accept: text/event-stream

响应头:

Content-Type: text/event-stream
Cache-Control: no-cache
Connection: keep-alive

事件流格式:

1. 增量消息事件 (可多次发送)

event: message
data: {"delta": "您好，"}

event: message
data: {"delta": "我们的产品"}

2. 最终结果事件 (发送一次后关闭连接)

event: final
data: {"reply": "完整回复内容", "confidence": 0.92, "shouldTransfer": false}

3. 错误事件 (发生错误时发送)

event: error
data: {"code": "INTERNAL_ERROR", "message": "错误描述"}

事件序列保证:

• message* (0 或多次) → final (1 次) → 连接关闭
• 或 message* (0 或多次) → error (1 次) → 连接关闭

4.1.3 错误响应

401 Unauthorized - 认证失败

{
  "code": "UNAUTHORIZED",
  "message": "Missing required header: X-API-Key",
  "details": []
}

400 Bad Request - 请求参数错误

{
  "code": "INVALID_REQUEST",
  "message": "缺少必填字段: sessionId",
  "details": []
}

400 Bad Request - 租户 ID 格式错误

{
  "code": "INVALID_TENANT_ID",
  "message": "Invalid tenant ID format. Expected: name@ash@year (e.g., szmp@ash@2026)",
  "details": []
}

500 Internal Server Error - 服务内部错误

{
  "code": "INTERNAL_ERROR",
  "message": "LLM 调用失败",
  "details": []
}

503 Service Unavailable - 服务不可用

{
  "code": "SERVICE_UNAVAILABLE",
  "message": "向量数据库连接失败",
  "details": []
}

---

4.2 健康检查

接口路径: GET /ai/health

功能描述: 检查 AI 服务是否正常运行，用于服务监控和负载均衡健康探测。

4.2.1 请求参数

无需请求参数，无需认证头。

4.2.2 响应格式

200 OK - 服务正常

{
  "status": "healthy"
}

503 Service Unavailable - 服务不健康

{
  "status": "unhealthy"
}

---

5. 调用示例

5.1 Java 调用示例（非流式）

import org.springframework.http.*;
import org.springframework.web.client.RestTemplate;

public class AIServiceClient {

    private final RestTemplate restTemplate;
    private final String aiServiceUrl = "http://ai-service:8080";
    private final String apiKey = "your_api_key_here";

    public ChatResponse generateReply(String tenantId, ChatRequest request) {
        HttpHeaders headers = new HttpHeaders();
        headers.setContentType(MediaType.APPLICATION_JSON);
        headers.set("X-API-Key", apiKey);
        headers.set("X-Tenant-Id", tenantId);

        HttpEntity<ChatRequest> entity = new HttpEntity<>(request, headers);

        ResponseEntity<ChatResponse> response = restTemplate.postForEntity(
            aiServiceUrl + "/ai/chat",
            entity,
            ChatResponse.class
        );

        return response.getBody();
    }
}

5.2 Java 调用示例（流式）

import org.springframework.web.reactive.function.client.WebClient;
import reactor.core.publisher.Flux;

public class AIServiceStreamClient {

    private final WebClient webClient;
    private final String apiKey = "your_api_key_here";

    public Flux<ServerSentEvent<String>> generateReplyStream(
        String tenantId,
        ChatRequest request
    ) {
        return webClient.post()
            .uri("/ai/chat")
            .header("X-API-Key", apiKey)
            .header("X-Tenant-Id", tenantId)
            .header("Accept", "text/event-stream")
            .bodyValue(request)
            .retrieve()
            .bodyToFlux(ServerSentEvent.class);
    }
}

5.3 cURL 调用示例

# 非流式调用
curl -X POST http://ai-service:8080/ai/chat \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your_api_key_here" \
  -H "X-Tenant-Id: szmp@ash@2026" \
  -d '{
    "sessionId": "kf_001_wx123456_1708765432000",
    "currentMessage": "我想了解产品价格",
    "channelType": "wechat"
  }'

# 流式调用
curl -X POST http://ai-service:8080/ai/chat \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your_api_key_here" \
  -H "X-Tenant-Id: szmp@ash@2026" \
  -H "Accept: text/event-stream" \
  -d '{
    "sessionId": "kf_001_wx123456_1708765432000",
    "currentMessage": "我想了解产品价格",
    "channelType": "wechat"
  }'

# 健康检查（无需认证）
curl http://ai-service:8080/ai/health

---

6. 业务逻辑说明

6.1 会话管理

• 会话标识: sessionId 用于唯一标识一个对话会话
• 自动持久化: AI 中台会自动保存会话历史，无需调用方每次传递完整历史
• 可选历史: 调用方可通过 history 字段提供外部历史，AI 中台会合并处理
• 租户隔离: 相同 sessionId 在不同 tenantId 下视为不同会话

6.2 RAG 检索增强

• 自动触发: AI 中台会根据用户问题自动判断是否需要检索知识库
• 多知识库: 支持按知识库类型（产品知识、FAQ、话术模板等）分类检索
• 置信度评估: 检索结果质量会影响 confidence 评分
• 兜底策略: 检索失败或无结果时，AI 会基于通用知识回答并降低置信度

6.3 转人工建议

shouldTransfer 字段由以下因素决定：

• ✅ 置信度低于阈值（默认 0.6）
• ✅ 检索无结果或结果质量差
• ✅ 用户明确要求人工服务
• ✅ 意图识别命中"转人工"规则

注意: shouldTransfer=true 仅为建议，最终是否转人工由调用方（Java 主框架）决策。

6.4 意图识别与规则引擎

• 前置处理: 用户消息会先经过意图识别
• 固定回复: 命中固定规则时直接返回预设话术（跳过 LLM 调用）
• 话术流程: 命中流程规则时进入多轮引导对话
• 定向检索: 命中 RAG 规则时使用指定知识库检索

6.5 输出护栏

• 禁词过滤: AI 回复会自动过滤禁词（竞品名称、敏感词等）
• 替换策略: 支持星号替换、文本替换、整条拦截三种策略
• 行为约束: Prompt 中注入行为规则（如"不承诺具体赔偿金额"）

---

7. 性能与限制

7.1 性能指标

指标	非流式	流式
首字响应时间	1-3 秒	200-500 毫秒
完整响应时间	2-5 秒	3-8 秒
并发支持	100+ QPS	50+ QPS

7.2 限制说明

• 消息长度: 单条消息最大 4000 字符
• 历史长度: 建议历史消息不超过 20 轮（AI 中台会自动截断）
• 超时设置: 建议调用方设置 10 秒超时（非流式）、30 秒超时（流式）
• 重试策略: 503 错误建议指数退避重试，500 错误建议降级处理

---

8. 错误码参考

错误码	HTTP 状态码	说明	处理建议
UNAUTHORIZED	401	认证失败（缺少或无效 API Key）	检查 X-API-Key 请求头
INVALID_REQUEST	400	请求参数错误	检查必填字段和参数格式
MISSING_TENANT_ID	400	缺少租户 ID	添加 X-Tenant-Id 请求头
INVALID_TENANT_ID	400	租户 ID 格式错误	使用正确格式：name@ash@year
INTERNAL_ERROR	500	服务内部错误	降级处理或重试
LLM_ERROR	500	LLM 调用失败	降级处理或重试
SERVICE_UNAVAILABLE	503	服务不可用	指数退避重试
QDRANT_ERROR	503	向量库不可用	指数退避重试
STREAMING_ERROR	200 (SSE)	流式传输错误	关闭连接并重试

---

9. 最佳实践

9.1 API Key 管理

• API Key 由 AI 中台管理员通过管理后台分配
• 建议为不同环境（开发/测试/生产）使用不同的 API Key
• API Key 应存储在配置文件或环境变量中，不要硬编码
• 定期轮换 API Key 以提高安全性

9.2 会话 ID 生成规范

建议格式: {业务前缀}_{租户ID}_{渠道用户ID}_{时间戳}

示例: kf_001_wx123456_1708765432000

9.3 流式 vs 非流式选择

• 流式: 适用于 Web/App 实时对话场景，用户体验更好
• 非流式: 适用于批量处理、异步任务、API 集成场景

9.4 降级策略建议

public ChatResponse generateReplyWithFallback(String tenantId, ChatRequest request) {
    try {
        return aiServiceClient.generateReply(tenantId, request);
    } catch (ServiceUnavailableException e) {
        // 降级策略 1: 返回固定话术
        return ChatResponse.builder()
            .reply("抱歉，当前咨询量较大，请稍后再试或转人工服务。")
            .confidence(0.0)
            .shouldTransfer(true)
            .build();
    } catch (Exception e) {
        // 降级策略 2: 直接转人工
        return ChatResponse.builder()
            .reply("系统繁忙，正在为您转接人工客服...")
            .confidence(0.0)
            .shouldTransfer(true)
            .transferReason("AI 服务异常")
            .build();
    }
}

9.5 监控指标建议

• ✅ 接口响应时间（P50/P95/P99）
• ✅ 接口成功率
• ✅ 置信度分布
• ✅ 转人工率
• ✅ 错误码分布

---

10. 变更日志

版本	日期	变更内容
v1.1.0	2026-02-27	新增流式输出支持、意图识别、输出护栏
v1.0.0	2026-02-20	初始版本，支持基础对话生成和健康检查

---

11. 联系方式

• 技术支持: AI 中台开发团队
• 问题反馈: 提交 Issue 到项目仓库
• 文档更新: 参考 spec/ai-service/openapi.provider.yaml

---

文档生成时间: 2026-02-27 契约版本: v1.1.0 维护状态: ✅ 活跃维护