Higress 网关中 AI 代理功能对无请求体接口的兼容性问题解析

问题背景

在使用 Higress 网关的 AI 代理功能时，开发者发现调用 AI 服务兼容接口 /v1/models 时会出现超时问题。这个问题特别出现在启用了全 PATH 透传功能的情况下，而直接调用 AI 服务则能正常返回结果。

问题现象分析

当通过 Higress 网关调用 /v1/models 接口时，请求会超时失败。通过网关日志可以看到请求确实到达了网关，但未能成功转发到后端服务。有趣的是，其他接口如 /v1/chat/completions 和 /v1/responses 都能正常工作。

根本原因

经过深入排查，发现问题的根源在于请求头中包含了 Content-Type 头信息。/v1/models 是一个 GET 请求，按照 HTTP 规范不应该包含请求体，因此也不应该设置 Content-Type 头。然而，Higress 的 AI 代理插件在看到 Content-Type 头后会等待请求体的到来，导致请求处理被阻塞，最终超时。

解决方案

针对这个问题，有以下几种解决方案：

1. 客户端修改：对于 GET 请求，特别是像 /v1/models 这样不需要请求体的接口，客户端不应该发送 Content-Type 头。这是最直接的解决方案。

2. 插件优化：Higress 的 AI 代理插件可以增加对请求方法的判断，对于明确不需要请求体的方法（如 GET），即使看到 Content-Type 头也不等待请求体。这种优化可以提升插件的健壮性。

3. 路由配置：为 /v1/models 这类特殊接口配置独立的路由规则，绕过 AI 代理插件的处理。

技术深入

这个问题揭示了 HTTP 协议实现中的一个重要细节：虽然 Content-Type 头通常用于指示请求体的媒体类型，但它的存在并不自动意味着请求一定包含请求体。对于 GET 请求，即使客户端错误地包含了 Content-Type 头，服务器也不应该无限期等待不存在的请求体。

在网关设计中，正确处理这类边缘情况非常重要，因为网关需要兼容各种客户端的实现，包括那些可能不完全遵循 HTTP 规范的客户端。

最佳实践建议

1. 客户端开发时应严格遵循 HTTP 规范，GET 请求不应包含 Content-Type 头，除非确实需要发送请求体（虽然这种情况很少见）。

2. 网关插件开发时应考虑各种异常情况，包括但不限于：

   • 多余的头部信息
   • 不符合规范的请求组合
   • 超时处理机制

3. 对于 AI 代理这类功能，建议提供详细的接口文档，明确说明各接口的请求方法和是否需要请求体。

总结

Higress 网关中 AI 代理功能对 /v1/models 接口的超时问题，揭示了 HTTP 协议实现和网关设计中的重要细节。通过这个问题，我们不仅找到了解决方案，也获得了关于 API 网关设计的宝贵经验。未来 Higress 可能会在这方面进行优化，以提供更好的兼容性和用户体验。