用 langchaingo 接入 Google Vertex AI 生成文本嵌入向量：示例实战与源码解析

用 langchaingo 接入 Google Vertex AI 生成文本嵌入向量示例实战与源码解析【免费下载链接】langchaingoLangChain for Go, the easiest way to write LLM-based programs in Go项目地址: https://gitcode.com/GitHub_Trending/la/langchaingo导读本文基于 langchaingo 仓库中的 Vertex AI Embedding 示例 展开讲解如何在 Go 程序中通过 langchaingo 调用 Google Vertex AI 的文本嵌入Embedding服务将自然语言文本转换为可供语义搜索、文本分类等任务使用的数值向量。读完本文你将掌握环境变量配置、vertex.New客户端初始化、CreateEmbedding调用方式并理解其背后的双层客户端设计与批量嵌入实现原理。示例概述这个程序做什么仓库中的示例程序 vertex-embedding-example.go 是一个最小可运行的程序核心流程只有四步从环境变量读取 Google Cloud 项目 ID 与区域location使用 langchaingo 的 Vertex AI 客户端创建连接为文本I am a human生成嵌入向量将结果向量打印到控制台。嵌入向量本质上是将文本映射为一个定长的浮点数数组如 768 或 3072 维。在向量空间中语义相近的文本其向量距离更近因此嵌入是语义搜索、文本分类、聚类、推荐等现代 NLP 任务的基石。运行前准备环境与认证运行该示例前需要满足以下前提一个已启用 Vertex AI API 的 Google Cloud 项目设置环境变量VERTEX_PROJECT为你的 GCP 项目 ID设置环境变量VERTEX_LOCATION为 GCP 区域例如us-central1示例源码注释也建议不确定时使用us-central1具备访问 Vertex AI 的认证凭据见下文“认证方式”小节。配置完成后在示例目录下直接运行go run vertex-embedding-example.go代码逐行解析完整示例代码如下来源vertex-embedding-example.go// Set the VERTEX_PROJECT to your GCP project with Vertex AI APIs enabled. // Set VERTEX_LOCATION to a GCP location (region); if youre not sure about // the location, set us-central1 package main import ( context fmt log os github.com/tmc/langchaingo/llms/googleai github.com/tmc/langchaingo/llms/googleai/vertex ) func main() { ctx : context.Background() project : os.Getenv(VERTEX_PROJECT) location : os.Getenv(VERTEX_LOCATION) llm, err : vertex.New(ctx, googleai.WithCloudProject(project), googleai.WithCloudLocation(location)) if err ! nil { log.Fatal(err) } embeddings, err : llm.CreateEmbedding(ctx, []string{I am a human}) if err ! nil { log.Fatal(err) } fmt.Println(embeddings) }几个值得注意的要点导入路径是github.com/tmc/langchaingo/llms/googleai/vertex与面向 Gemini API Key 的llms/googleai包提供者区分开来vertex子包面向 Google Cloud Vertex AI 平台需要项目 ID 与区域信息客户端配置通过函数式选项googleai.Option注入WithCloudProject设置项目 IDWithCloudLocation设置区域CreateEmbedding接受[]string文本切片、返回[][]float32说明它天然支持批量文本输入运行成功后会看到一行浮点数向量输出例如[[0.012345 ... -0.045678]]。源码原理为什么顶点客户端是“双客户端”从源码结构看Vertex 客户端的初始化并不像表面那样简单。查看 llms/googleai/vertex/new.go 中的New函数可以发现它实际创建了两个底层客户端genai.NewClient(ctx, CloudProject, CloudLocation, ...)用于 Gemini 系列模型的对话、生成等能力palmclient.New(ctx, CloudProject, CloudLocation, ...)专门用于嵌入请求。其结构体定义vertex.go 附近的Vertex类型同时持有client *genai.Client与palmClient *palmclient.PaLMClient两个字段。源码注释明确说明了原因Right now, the Vertex Gemini SDK doesnt support embeddings; therefore, for embeddings we also hold a palmclient.即当前 Vertex 的 Gemini SDK 尚未支持嵌入能力因此 langchaingo 为嵌入专门保留了 PaLM 客户端通道。这是理解该模块设计的关键事实。嵌入请求的具体实现在 llms/googleai/vertex/embeddings.gofunc (g *Vertex) CreateEmbedding(ctx context.Context, texts []string) ([][]float32, error) { embeddings, err : g.palmClient.CreateEmbedding(ctx, palmclient.EmbeddingRequest{ Input: texts, }) ... if len(texts) ! len(embeddings) { return embeddings, fmt.Errorf(returned %d embeddings for %d texts, len(embeddings), len(texts)) } return embeddings, nil }实现中还有两层防御性校验返回结果为空时抛出empty response错误返回向量数量与输入文本数量不一致时抛出明确的数量不匹配错误。对应测试用例见 llms/googleai/vertex/embeddings_test.go覆盖了单文本、多文本、空响应、数量不匹配、底层 API 错误、空输入等多种场景。认证方式除环境变量外认证凭据可以通过函数式选项注入。查看 llms/googleai/option.go 可看到以下选项WithCredentialsFile(credentialsFile string)使用服务账号或刷新令牌 JSON 凭据文件认证WithCredentialsJSON(credentialsJSON []byte)直接传入凭据 JSON 字节WithHTTPClient/WithGRPCConn自定义 HTTP 客户端或 gRPC 连接后者常用于测试场景见 option.go。Vertex 模式通常依赖 Google Cloud 默认凭据如GOOGLE_APPLICATION_CREDENTIALS环境变量指向的服务账号 JSON这部分由底层cloud.google.com/go/vertexai驱动。此外DefaultOptions 中可见默认配置默认嵌入模型为embedding-001、默认对话模型为gemini-2.0-flash、默认MaxTokens为 2048、默认温度为 0.5。扩展用法默认嵌入模型与批量嵌入示例只嵌入了一条文本但CreateEmbedding的签名支持批量输入。若需指定其他嵌入模型可在初始化时追加googleai.WithDefaultEmbeddingModel(modelName)选项定义见 option.go。另外需要说明上文讨论的是VertexGoogle Cloud路径若你使用的是 Gemini API Key 而非 Vertex AI则可以改用llms/googleai包的GoogleAI客户端其嵌入实现在 llms/googleai/embeddings.go走的是 Gemini Embedding Batch API。该实现有一个明确的工程细节The Gemini Embedding Batch API allows up to 100 documents per batch, so send a request every 100 documents and when we hit the last document.即每条请求最多携带 100 个文档代码会在每满 100 条以及遍历到最后一条时调用BatchEmbedContents分批发送避免超出 API 上限并把各批次结果合并后一次性返回。这一细节对需要嵌入大量文本的生产场景很有参考价值。常见问题与排查建议认证失败确认 GCP 项目已启用 Vertex AI API并确保运行环境的凭据服务账号 JSON / ADC对项目有aiplatform相关权限VERTEX_PROJECT/VERTEX_LOCATION为空vertex.New会用空字符串创建客户端通常在首次请求时失败。请先echo $VERTEX_PROJECT检查环境变量返回empty response错误多发生在输入为空切片时这是 embeddings.go 的显式校验逻辑返回数量不匹配错误底层服务返回的向量数少于输入文本数可尝试减少单批文本数量后重试资源释放Vertex类型提供了Close()方法见 vertex/new.go关闭底层 genai 连接以避免 gRPC 连接泄漏长驻服务中记得在退出时调用。总结通过 langchaingo 的llms/googleai/vertex包你只需十几行 Go 代码即可把 Vertex AI 的文本嵌入能力接入自己的应用。理解其“Gemini 客户端 PaLM 嵌入客户端”的双通道设计以及分批调用、数量校验等实现细节能帮助你在实际项目中更稳健地使用嵌入向量为语义搜索、文本分类等下游任务打好数据基础。【免费下载链接】langchaingoLangChain for Go, the easiest way to write LLM-based programs in Go项目地址: https://gitcode.com/GitHub_Trending/la/langchaingo创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考