CloudWeGo Eino 接入自定义 OpenAI 兼容 API 实战

在 Go 生态中构建 LLM 应用，CloudWeGo 的 Eino 框架是一个值得关注的选择。它提供了聊天模型、工具调用、图编排和 ReAct Agent，风格类似 LangChain，但为 Go 量身定制。其中 OpenAI 组件（github.com/cloudwego/eino-ext/components/model/openai）是连接 vLLM、Ollama 的 /v1 端点、LiteLLM 或网关等兼容服务的常用入口。有开发者在 Go 1.27.2 上使用 eino v0.7.13 和 eino-ext OpenAI 组件 v0.1.13，针对本地 mock server 进行了详细测试，记录了实际发出的 HTTP 请求细节。本文基于这些实测数据，梳理接入自定义 API 时的关键配置与陷阱。

最小配置：三个字段与一个编译坑

安装依赖后，首次 go build 可能触发一个编译错误：Eino 依赖的 sonic v1.14.1 在 Go 1.27 上因 undefined: GoMapIterator 失败。解决方法是手动升级 sonic 到最新版并执行 go mod tidy。

模型初始化本身很简洁，核心是 BaseURL、APIKey 和 Model 三个字段。需要留意的是，结构体注释称 BaseURL 用于 Azure，但实际上所有非 Azure 客户端都会使用它。Eino 不会从环境变量读取 OPENAI_API_KEY 或 OPENAI_BASE_URL，必须显式传入。

cm, err := openai.NewChatModel(ctx, &openai.ChatModelConfig{
    BaseURL: "https://your-gateway.com/v1",
    APIKey:  os.Getenv("YOUR_API_KEY"),
    Model:   "YOUR_MODEL_ID",
    Timeout: 60 * time.Second,
})

测试确认，请求路径严格为 BaseURL + /chat/completions，不会自动补全 /v1。如果 BaseURL 只写 https://host，路径会变成 /chat/completions，多数网关会返回 404。请求体默认极简，仅包含 messages 和 model，不发送 temperature 或 max_tokens。Timeout 字段默认不设置任何超时，因此必须手动配置或传入自定义 HTTPClient。

采样参数用指针，零值会被发送

Temperature、MaxTokens、TopP 等采样参数都是指针类型。设置 Temperature: &zero 会真的在请求体中发送 "temperature":0，而某些 Python 封装会将零值视为未设置而丢弃。此外，可以通过 model.WithTemperature 等函数在单次调用中覆盖配置，甚至用 model.WithModel 临时切换模型，无需重建客户端。

流式调用 cm.Stream 会自动加上 "stream":true 和 "stream_options":{"include_usage":true}。如果兼容服务拒绝 stream_options 字段，流式调用会失败，而 Generate 正常。对于推理模型，响应中的 reasoning_content 会映射到 out.ReasoningContent；内联的 <think> 标签则保留在 out.Content 中，框架不会剥离。

没有自动重试，需要自己加 Transport

这是最令人意外的行为。测试显示，面对 401、400、429（带 Retry-After: 2）、500 或 503，Eino 都只发送一次请求，绝不重试。Retry-After 被忽略。对于 CLI 工具可能无伤大雅，但对于生产服务，一次 429 就可能导致用户可见的失败。

错误检查需要匹配 eino-ext 自己的 *openai.APIError 类型，而不是底层 go-openai 分支的类型，因为组件做了转换。

var apiErr *openai.APIError
if errors.As(err, &apiErr) && apiErr.HTTPStatusCode == 429 {
    // 处理限流
}

弥补重试的干净做法是实现一个 http.RoundTripper，缓存请求体并在 429 或 5xx 时进行指数退避重试。测试中，一个返回两次 429 后成功的 mock 服务，经过三次请求（间隔约两秒）后正常返回；永久 503 则重试三次后返回错误；401 仍只请求一次。需注意 http.Client.Timeout 覆盖所有重试的总体时间，应留足余量。

http.RoundTripper 是 Go 标准库 net/http 包中的接口，定义在 http.Client 的 Transport 字段。每个 HTTP 请求在发出前和收到响应后，都会经过 RoundTrip(*Request) (*Response, error) 方法。自定义 RoundTripper 可以无侵入地拦截请求，实现重试、日志、限流、添加认证头等横切逻辑。实现重试时需注意：http.Request.Body 是一次性读取的 io.ReadCloser，首次发送后已被消费，重试前必须缓存原始 body 并重新构造 io.NopCloser。此外，应只对幂等请求（如 GET）或明确安全的场景（如 LLM 推理请求，通常无副作用）重试，并对 429 响应遵循 Retry-After 头，对 5xx 采用指数退避加抖动，同时设置最大重试次数避免无限循环。

ReAct Agent 的 MaxStep：步数不等于工具调用次数

创建 ReAct Agent 时，MaxStep 容易误解。测试发现，MaxStep 统计的是图节点的执行次数，每一轮循环包含一个模型节点和一个工具节点。默认 MaxStep 为 12 时，实际发出了 7 次模型请求和 6 次工具调用，然后返回 [GraphRunError] exceeds max steps。设置 MaxStep: 40 则对应 20 次模型请求和 20 次工具调用。也就是说，工具调用次数约为 MaxStep / 2。

每次请求都会重新发送完整历史，40 步运行的最后一次请求携带了 39 条消息，上下文长度增长很快。可以通过 errors.Is(err, compose.ErrExceedMaxSteps) 判断是否触达上限，并给用户返回部分结果或提示。

接入检查清单

• BaseURL 必须带 /v1，Eino 只追加 /chat/completions。
• 显式传入 APIKey，环境变量不会被读取。
• 设置 Timeout 或提供自定义 HTTPClient，默认无超时。
• 自行通过 Transport 实现重试，错误匹配 eino-ext 的 *openai.APIError。
• 每次流式请求都会带上 stream_options.include_usage。
• 将 MaxStep 视为期望工具轮次的两倍左右来设置。

这些细节来自实际网络请求的抓包与验证，对于使用 Eino 对接自托管模型或 API 网关的 Go 开发者，能帮助避开常见的配置陷阱。

背景补充

Eino 的 compose 包用图（Graph）来表达执行流：节点（Node）代表一个计算单元，边（Edge）定义节点之间的依赖与跳转。ReAct Agent 在内部被编译成一张循环图——模型节点产出工具调用意图，工具节点执行调用并回填结果，再由条件边决定是否回到模型节点。MaxStep 限制的是这张图中节点被执行的累计次数，而非某个单一动作的重复次数。因此，一轮完整的“思考-行动”循环通常消耗两个步数（模型节点 + 工具节点），这解释了工具调用次数约为 MaxStep / 2 的现象。理解这一图执行模型，有助于正确设置步数上限并在超限时定位是哪类节点导致了消耗。