展开本页目录
开始前准备什么
- Go 1.25 或以上；本次测试 Go 1.26.2。
- 支持 Chat Completions 的准确 Model ID 和自己的 Key。
- 先下载 go.mod、go.sum、main.go，使用独立示例目录。
- 锁定 SDK
- 设置地址与认证
- 限定请求时间
- 离线验证形状
- 核对真实结果
下载完整 Go 项目
固定 go.mod/go.sum、默认预览和本地 HTTP 测试。
三个选项与两层超时
下载文件的 HTTP 客户端额外拒绝重定向，避免把模型认证带到另一个地址。context 控制这次操作生命周期，HTTP Timeout 控制客户端；取消本地等待不等于上游停止处理，也不是免费重试依据。
main.go 核心片段
go
client := openai.NewClient(
option.WithAPIKey(os.Getenv("tokenba_API_KEY")),
option.WithBaseURL("https://api.apizt.com/v1"),
option.WithMaxRetries(0),
option.WithHTTPClient(&http.Client{Timeout: 30*time.Second}),
)
ctx, cancel := context.WithTimeout(context.Background(), 30*time.Second)
defer cancel()
response, err := client.Chat.Completions.New(ctx,
openai.ChatCompletionNewParams{
Model: os.Getenv("tokenba_MODEL"),
Messages: []openai.ChatCompletionMessageParamUnion{
openai.UserMessage("仅回答 tokenba_OK"),
},
})
本站绘制的内容说明图：HTTP 超时与 context 分别控制客户端和操作；取消本地等待不证明上游取消或免计费。
依赖版本与请求协议
| 对象 | 固定设置 | 实际含义 |
|---|---|---|
| 模块 | github.com/openai/openai-go/v3 v3.73.0 | 使用官方 Go SDK v3 导入路径 |
| go.mod | go 1.25.0 | 本地 1.26.2 编译；较低版本未验证 |
| Base URL | https://api.apizt.com/v1 | SDK 拼成 /v1/chat/completions |
| 首个请求 | 用户文本；无工具、流式或图片 | 先只验证文字链路 |
- 对象
- 模块
- 固定设置
- github.com/openai/openai-go/v3 v3.73.0
- 实际含义
- 使用官方 Go SDK v3 导入路径
- 对象
- go.mod
- 固定设置
- go 1.25.0
- 实际含义
- 本地 1.26.2 编译；较低版本未验证
- 对象
- Base URL
- 固定设置
- https://api.apizt.com/v1
- 实际含义
- SDK 拼成 /v1/chat/completions
- 对象
- 首个请求
- 固定设置
- 用户文本；无工具、流式或图片
- 实际含义
- 先只验证文字链路
先运行预览与本地 HTTP 夹具
--offline 使用 httptest 临时服务接收一次 SDK POST，检查路径、方法与模型字段，再返回固定 Chat JSON。已验证固定回答 tokenba_OK；结果不来自真实模型。默认不加 --run 时不会发起模型请求。
在 go-chat 目录运行
bash
go mod download
go run .
go run . --offline
# 安全设置自己的 Key 与准确 Model ID 后
go run . --run
本站绘制的内容说明图：保留本页离线夹具通过范围，默认预览不调用模型；真实通道权限和费用仍需独立确认。
文字、流式与工具分开验收
| 功能 | 需要的证据 | 不要跳过 |
|---|---|---|
| 普通文字 | 状态、choices、正文、准确型号 | 非空 choices 后再读第一个结果 |
| 流式 | 逐段读取、结束事件、最终 stream.Err() | 收到第一段不等于完整结束 |
| 工具 | 工具名称、参数、执行、原 ID 回传、最终正文 | 文字回答不能当工具调用成功 |
| 视觉 | 正确 image_url 对象、可访问图片、视觉型号 | Chat 端点可用不代表型号会看图 |
- 功能
- 普通文字
- 需要的证据
- 状态、choices、正文、准确型号
- 不要跳过
- 非空 choices 后再读第一个结果
- 功能
- 流式
- 需要的证据
- 逐段读取、结束事件、最终 stream.Err()
- 不要跳过
- 收到第一段不等于完整结束
- 功能
- 工具
- 需要的证据
- 工具名称、参数、执行、原 ID 回传、最终正文
- 不要跳过
- 文字回答不能当工具调用成功
- 功能
- 视觉
- 需要的证据
- 正确 image_url 对象、可访问图片、视觉型号
- 不要跳过
- Chat 端点可用不代表型号会看图
保留失败阶段，避免盲目重发
- 收到 401，核对 Key 权限和是否加载了正确进程环境。
- 收到 404，检查最终路径与 Base URL，避免完整端点再次被 SDK 拼接。
- 收到 400，保存脱敏后的字段名和状态；先删除可选参数，再逐项验证。
- 超时或断连时，用稳定业务 ID 查实际处理状态与账户记录；本示例没有跨进程防重复保护。
把同一个小任务带进生产
记录 Go、SDK、模型 ID、协议、请求开始时间和实扣。正式服务先限制并发，分别统计文字、工具回合、缓存与重试。不要用单次 OK 推导吞吐量或全部型号兼容。
怎样确认已经完成
- Go 模块版本固定并可下载。
- 离线 POST 数量为 1，路径与 Model ID 正确。
- 真实请求与账单可对应，错误正文不泄露 Key。
- 流式结束与工具回传有独立记录。
常见问题
为什么 v3 的导入路径带 /v3？
它是 Go 模块主版本路径。go.mod 与源码 import 应同时使用 github.com/openai/openai-go/v3，不能混入旧版类型。
context 超时后能立即重试吗？
本地超时可能发生在上游已处理之后。先核对请求状态与账单，再按业务恢复规则决定。
这份下载包会自动调用 API 吗？
默认只预览。--offline 只访问本地夹具；显式 --run 才发送一次真实文字请求。