大模型Go SDK使用教程：从安装到第一个对话请求
想在 Go 项目里调用大模型，最直接的方式是引入官方或社区维护的 Go SDK。
这篇教程从零开始，带你完成环境准备、依赖安装、密钥配置和第一个对话请求，并覆盖几个新手最容易卡住的报错点。
先确认你的环境和账号条件
大模型 Go SDK 使用前，需要准备三样东西：
- 一个可用的 Go 开发环境，建议 Go 1.21 及以上版本，用
go version确认。 - 一个能访问目标大模型服务的 API Key，以及对应的 API 地址（Base URL）。不同厂商的地址和模型名称不同，以你所用平台的控制台为准。
- 一个空目录作为练习项目，避免在已有工程里直接试错。
初始化项目：
mkdir llm-demo && cd llm-demo
go mod init llm-demo执行后目录下会生成 go.mod，说明模块初始化成功。
安装大模型 Go SDK
以常见的 OpenAI 兼容 SDK 为例，安装命令是：
go get github.com/sashabaranov/go-openai如果你的服务商提供了自己的 Go SDK，把模块路径换成官方文档给出的地址即可。
安装完成后，go.mod 里会出现对应依赖，go.sum 也会生成，这是正常现象。
这里要提醒一点：SDK 模块路径和 API 地址是两回事。
SDK 负责帮你封装 HTTP 请求，API 地址决定请求发到哪个服务，两者不要混淆。
配置密钥并发出第一个请求
不要把 API Key 直接写死在代码里。
推荐用环境变量传入：
export LLM_API_KEY="你的API Key"
export LLM_BASE_URL="https://你的服务地址/v1"然后创建 main.go，写入最小可运行示例：
package main
import (
"context"
"fmt"
"os"
openai "github.com/sashabaranov/go-openai"
)
func main() {
config := openai.DefaultConfig(os.Getenv("LLM_API_KEY"))
config.BaseURL = os.Getenv("LLM_BASE_URL")
client := openai.NewClientWithConfig(config)
resp, err := client.CreateChatCompletion(
context.Background(),
openai.ChatCompletionRequest{
Model: "你的模型名称",
Messages: []openai.ChatCompletionMessage{
{Role: openai.ChatMessageRoleUser, Content: "用一句话解释什么是 Go 的 goroutine"},
},
},
)
if err != nil {
fmt.Println("请求失败:", err)
return
}
fmt.Println(resp.Choices[0].Message.Content)
}运行：
go run main.go如果终端打印出一段模型回复，说明大模型 Go SDK 使用链路已经打通。
常见报错怎么查
401 认证失败：先确认环境变量是否真的加载了，可以临时在代码里打印 Key 的前几位检查，但不要打印完整 Key。
再确认 Key 是否过期或被禁用。
连接超时或 DNS 错误：检查 LLM_BASE_URL 是否写错，尤其是协议头和 /v1 后缀。
服务器上可以用 curl -I 你的BaseURL 看是否能通。
404 模型不存在：模型名称必须和服务商控制台列出的完全一致，大小写和版本后缀都不能改。
返回内容为空：先看 resp.Choices 长度是否为 0，再检查请求里的 Model 和 Messages 是否都传了。
避坑与验证建议
- 密钥只放环境变量或密钥管理服务，不要提交到 Git。
- 生产环境给请求加上超时控制，例如
context.WithTimeout，避免请求挂死。 - 先用最小示例跑通，再封装成函数或服务，不要一上来就套框架。
- 验证是否成功，以终端输出模型回复为准；如果失败，优先看错误信息里的状态码和返回体。
大模型 Go SDK 使用本身不复杂，真正容易出错的是密钥配置、Base URL 和模型名称这三处。
按本文顺序走一遍，再用超时和错误处理加固，基本就能稳定接入。
