Java 与 Python AI 服务接口契约

Java 主服务和 Python AI 服务拆开之后，最大风险不是多了一次网络调用，而是接口边界说不清。

如果契约不清，问题会在两个服务之间来回甩：到底是请求没传全、AI 服务没处理好，还是主服务没有兜底？

请求要表达完整任务

Java 主服务调用 Python AI 服务时，不应该只传一句用户问题。

更合理的请求通常包括：

• 用户和租户上下文。
• 会话或任务 ID。
• 当前输入。
• 可用知识库或文档范围。
• 可用工具范围。
• 输出格式和超时要求。

这样 AI 服务才能在明确边界内执行，而不是靠自己猜业务意图。

响应要能被主服务处理

AI 服务返回的内容也不能只是一段自然语言。

至少要能表达回答内容、引用来源、使用的工具、Token 消耗、错误类型和是否需要继续追问。对于 Agent 场景，还可能需要返回中间步骤或事件流。

错误要分类型

模型超时、检索失败、权限不足、参数非法、输出校验失败，不应该都变成一个 500。

错误类型越清楚，Java 主服务越容易决定是重试、降级、提示用户、记录告警，还是阻断任务。

流式输出也需要契约

SSE 或其他流式协议不只是把文本一段段推给前端。

更好的事件流应该区分不同事件，例如开始生成、检索完成、工具调用、增量文本、引用信息、错误和结束。这样前端体验、日志记录和问题排查都会更清楚。

一句话先记住

Java 和 Python 服务之间的接口契约，决定了 AI 能力能否被业务系统可靠地调用、观察和兜底。

继续阅读

• 10-backend-for-ai-agent/003-sse-in-java.md
• 09-ai-agent-engineering/002-ai-call-log.md
• 09-ai-agent-engineering/008-fallback-and-degradation.md