使用 langchaingo 构建本地嵌入 + Milvus 向量库的 Go 示例：以全球城市相似度检索为例

使用 langchaingo 构建本地嵌入 Milvus 向量库的 Go 示例以全球城市相似度检索为例【免费下载链接】langchaingoLangChain for Go, the easiest way to write LLM-based programs in Go项目地址: https://gitcode.com/GitHub_Trending/la/langchaingo本篇文章基于 langchaingo 仓库中的huggingface-milvus-vectorstore-example实战示例完整讲解如何在 Go 程序中把 Hugging Face Text Embeddings InferenceTEI提供的本地嵌入能力与 Milvus 向量数据库结合起来先写入一批带有元数据的城市文档再通过自然语言查询执行相似度检索。读完本文你将掌握 langchaingo 中vectorstores/milvus包的初始化选项、AddDocuments与SimilaritySearch的调用方式以及如何用 Docker Compose 一键拉起 Milvus 与 TEI 本地推理服务。一、示例整体做什么该示例的全部代码位于 milvus_vectorstore_example.go核心流程分为四步搭建一个基于本地嵌入的 Milvus 向量库使用 Hugging Face 的 Text Embeddings InferenceTEI生成嵌入向量整个过程不依赖云端 API向向量库写入一批「城市」文档每条记录包含城市名、人口population与面积area元数据对存储的数据执行多次相似度搜索用自然语言查询找出符合地理条件的城市。示例数据覆盖了全球多个地区的城市日本城市Tokyo、Kyoto、Hiroshima、Kazuno、Nagoya、Toyota、Fukuoka欧洲城市Paris、London南美城市Santiago、Buenos Aires、Rio de Janeiro、Sao Paulo。每条城市记录由三部分构成PageContent城市名以及Metadata中的population单位百万和area单位平方千米例如Tokyo对应人口 9.7、面积 622。程序一共执行三组代表性检索Up to 5 Cities in Japan从数据集中找出位于日本的至多 5 个城市A City in South America定位一个南美城市Cities in Europe搜索欧洲城市。三组查询分别演示了「返回数量上限」「相似度分数阈值」等不同检索参数的组合用法。二、环境准备与基础设施启动运行该示例需要三样东西Docker 与 Docker Compose可用的 Go 开发环境go.mod 声明go 1.23.8并依赖github.com/milvus-io/milvus-sdk-go/v2 v2.4.0与github.com/tmc/langchaingo v0.1.14-pre.4通过仓库提供的 docker-compose.yml 启动 Milvus 与 Text Embeddings Inference 服务。docker-compose.yml 中定义了 4 个服务服务名镜像作用对外端口etcdquay.io/coreos/etcd:v3.5.0Milvus 的元数据存储配置了 revision 自动压缩与 4GB 后端配额内部 2379miniominio/minio:RELEASE.2020-12-03T00-03-10Z对象存储承载向量与日志数据默认账号minioadmin/minioadmin内部 9000standalonemilvusdb/milvusMilvus 单机版主服务通过环境变量ETCD_ENDPOINTS、MINIO_ADDRESS连接前两者宿主机19530:19530txt-inferenceghcr.io/huggingface/text-embeddings-inference默认cpu-latest标签本地运行thenlper/gte-base嵌入模型提供 OpenAI 兼容的嵌入接口宿主机5500:80启动命令docker compose up -d启动后Milvus 监听本机19530端口TEI 推理服务监听本机5500端口。如果宿主机不是 Linux x86_64 架构注意txt-inference服务显式声明了platform: linux/x86_64需保证 Docker 能模拟该平台。此外示例目录还提供了 Taskfile.ymlTaskfile 是 Makefile 的替代方案。如果你已在本地装好 TEI 的text-embeddings-router可以跳过容器直接用命令在5500端口起一个本地推理服务task run:text-embeddings-inference该任务内部执行text-embeddings-router --model-id thenlper/gte-large --port 5500使用的是gte-large模型与 docker-compose 中的gte-base不同两者均为 GTE 系列嵌入模型选择其一即可。三、代码逐段解析1. 用 OpenAI 兼容接口接入 TEI 本地嵌入服务langchaingo 的openai包允许通过WithBaseURL把请求转发到任意 OpenAI 兼容端点。示例利用这一点指向本机 TEI 服务从而获得纯本地的嵌入能力const ( poolSize 5 baseURL http://localhost:5500 ) llm, err : openai.New(openai.WithBaseURL(baseURL)) if err ! nil { log.Fatal(err) } embedder, err : embeddings.NewEmbedder(llm) if err ! nil { log.Fatal(err) }embeddings.NewEmbedder见 embeddings/embedding.go接收一个实现了EmbedderClient接口即CreateEmbedding(ctx, texts) ([][]float32, error)的客户端返回*EmbedderImpl。EmbedderImpl内部提供EmbedDocuments批量生成文档向量支持按BatchSize分批与EmbedQuery为单条查询生成向量两个方法并被用作向量库的embeddings.Embedder。2. 创建 Milvus 向量库实例接下来通过milvus.New创建向量库完整选项实现见 vectorstores/milvus/options.goidx, err : entity.NewIndexAUTOINDEX(entity.L2) if err ! nil { log.Fatal(err) } ctx : context.Background() milvusConfig : client.Config{ Address: http://localhost:19530, } store, errNs : milvus.New( ctx, milvusConfig, milvus.WithDropOld(), milvus.WithCollectionName(langchaingo_example), milvus.WithIndex(idx), milvus.WithEmbedder(embedder), )这里用到了几个关键选项WithDropOld()初始化时若同名集合已存在则先删除再重建底层调用DropCollection保证每次运行都是干净状态WithCollectionName(langchaingo_example)指定集合名WithIndex(idx)指定向量索引。示例使用entity.NewIndexAUTOINDEX(entity.L2)即由 Milvus 自动选择索引类型度量方式为 L2 欧氏距离WithEmbedder(embedder)绑定上一步创建的本地嵌入器。从 vectorstores/milvus/options.go 的源码看milvus.New会先应用所有选项其中embedder与index为必填项缺失会返回ErrInvalidOptions。其余配置项均带默认值配置项默认值说明集合名LangChainGoCollection可用WithCollectionName覆盖一致性级别entity.ClSession可用WithConsistencyLevel覆盖主键字段pk可用WithPrimaryField覆盖文本字段text可用WithTextField覆盖最大长度默认 65535可用WithMaxTextLength调整元数据字段meta可用WithMetaField覆盖向量字段vector可用WithVectorField覆盖度量类型entity.L2可用WithMetricType覆盖搜索 EF 参数10可用WithEF覆盖未指定搜索参数时自动生成 HNSW 搜索参数分片数entity.DefaultShardNumber可用WithShards覆盖其他可选选项还包括WithPartitionName分区名、WithSearchParameters自定义搜索参数与WithSkipFlushOnWrite写入时跳过 flush。从初始化流程看见 vectorstores/milvus/milvus.gomilvus.New依次完成建立客户端连接 → 检查集合是否存在 → 按需删除旧集合 → 初始化创建集合 schema、抽取字段、创建索引、生成搜索参数、加载集合到内存最终返回可直接使用的Store。3. 向向量库写入城市文档写入操作调用store.AddDocuments一次性传入 13 份文档。AddDocuments是 vectorstores/vectorstores.go 中VectorStore接口定义的两个核心方法之一type VectorStore interface { AddDocuments(ctx context.Context, docs []schema.Document, options ...Option) ([]string, error) SimilaritySearch(ctx context.Context, query string, numDocuments int, options ...Option) ([]schema.Document, error) }示例中的写入代码type meta map[string]any _, errAd : store.AddDocuments(context.Background(), []schema.Document{ {PageContent: Tokyo, Metadata: meta{population: 9.7, area: 622}}, {PageContent: Kyoto, Metadata: meta{population: 1.46, area: 828}}, // ... 其余城市略 {PageContent: Sao Paulo, Metadata: meta{population: 22.6, area: 1523}}, }) if errAd ! nil { log.Fatalf(AddDocument: %v\n, errAd) }每条文档的PageContent是城市名Metadata里附带数值型的人口与面积这些元数据会随向量一起存入 Milvus 的meta字段后续检索结果会原样带回。4. 执行相似度检索含分数阈值示例把三组查询组织成exampleCase结构通过循环统一调用SimilaritySearchtype exampleCase struct { name string query string numDocuments int options []vectorstores.Option } exampleCases : []exampleCase{ { name: Up to 5 Cities in Japan, query: Which of these are cities are located in Japan?, numDocuments: 5, options: []vectorstores.Option{ vectorstores.WithScoreThreshold(0.8), }, }, { name: A City in South America, query: Which of these are cities are located in South America?, numDocuments: 1, options: []vectorstores.Option{ vectorstores.WithScoreThreshold(0.8), }, }, { name: Cities in Europe, query: Which of these are cities are located in Europe?, numDocuments: 100, options: []vectorstores.Option{ vectorstores.WithScoreThreshold(.4), }, }, } for ecI, ec : range exampleCases { docs, errSs : store.SimilaritySearch(ctx, ec.query, ec.numDocuments, ec.options...) if errSs ! nil { log.Fatalf(query1: %v\n, errSs) } results[ecI] docs }三组用例分别演示了不同的检索策略日本城市返回最多 5 条分数阈值 0.8语义上「东京、京都、广岛等属于日本」这类城市会被召回南美城市只返回 1 条同样用 0.8 的高阈值收紧结果欧洲城市numDocuments设为 100放宽到全部候选但把阈值降到 0.4展示低阈值下返回更多候选的效果。WithScoreThreshold等检索选项定义在 vectorstores/options.go该文件还提供了WithFilters按元数据过滤、WithNameSpace、WithEmbedder为单次检索临时指定嵌入器和WithDeduplicater写入前去重等选项。ScoreThreshold字段类型为float32用于过滤相似度分数低于阈值的文档。5. 输出结果检索完成后程序按用例序号打印结果并把每份文档格式化为「城市名 (pop: 人口 area: 面积)」的形式for ecI, ec : range exampleCases { texts : make([]string, len(results[ecI])) for docI, doc : range results[ecI] { texts[docI] fmt.Sprintf(%s (pop: %v area: %f), doc.PageContent, doc.Metadata[population], doc.Metadata[area]) } fmt.Printf(%d. case: %s\n, ecI1, ec.name) fmt.Printf( result: %s\n, strings.Join(texts, , )) }输出类似Results: 1. case: Up to 5 Cities in Japan result: Tokyo (pop: 9.7 area: 622.000000), Kyoto (pop: 1.46 area: 828.000000), ... 2. case: A City in South America result: Santiago (pop: 6.9 area: 641.000000) 3. case: Cities in Europe result: Paris (pop: 11 area: 105.000000), London (pop: 9.5 area: 1572.000000), ...四、运行示例完成环境准备后在示例目录下执行docker compose up -d # 启动 Milvus 与 TEI go mod tidy # 拉取依赖 go run milvus_vectorstore_example.go程序启动后会依次完成向量库初始化、文档写入与三组检索并把结果打印到终端。可以修改查询语句、numDocuments、分数阈值或增删城市文档来观察结果变化——这正是理解「嵌入 向量检索」语义匹配行为的直观方式。五、底层原理与注意事项本地嵌入如何生效示例没有调用 OpenAI 云端接口而是把openai.New(openai.WithBaseURL(http://localhost:5500))指向 TEI 服务。TEI 的 HTTP 接口与 OpenAI 的嵌入接口兼容因此 langchaingo 的openai客户端可以直接复用embeddings.NewEmbedder再把该客户端包装成向量库所需的Embedder。整个流程中文本不离开本机适合对数据隐私或成本敏感的场景。初始化自动建集合在 vectorstores/milvus/milvus.go 的init流程中若集合尚不存在langchaingo 会根据默认字段pk、text、meta、vector自动创建 schema 并建立索引无需手工在 Milvus 侧预建集合WithDropOld则让重复运行示例时旧数据被自动清空。SDK 迁移提示需要注意的是vectorstores/milvus/milvus.go 包注释明确说明该实现依赖的github.com/milvus-io/milvus-sdk-go/v2已于 2025 年 3 月 21 日被 Milvus 维护者归档新 SDK 位于github.com/milvus-io/milvus/client/v2。langchaingo 已规划向新 SDK 迁移会带来破坏性变更并提供了迁移参考文档 vectorstores/milvus/v2/README.md。因此本文使用的v2版 SDK 相关 API 属于当前仓库中的既有实现后续升级时需关注迁移公告。六、动手扩展建议修改查询语义把query换成「Which city has the largest population?」「Find a capital city」等观察向量检索对不同自然语言表述的响应差异调整阈值对比WithScoreThreshold(0.4)与WithScoreThreshold(0.8)的召回数量理解阈值与精确率/召回率的权衡增加城市在AddDocuments的文档列表中追加新城市及人口、面积元数据验证新数据无需改动检索代码即可被命中尝试过滤结合vectorstores.WithFilters在检索时按元数据条件过滤可与本示例的纯向量检索形成对照。通过这个小而完整的示例你已经掌握了 langchaingo 中「本地嵌入 Milvus 向量库」的完整链路从基础设施编排、嵌入器接入到文档写入与带阈值的相似度检索。这一套模式可以直接迁移到 RAG检索增强生成、语义搜索、推荐召回等更复杂的应用场景中。【免费下载链接】langchaingoLangChain for Go, the easiest way to write LLM-based programs in Go项目地址: https://gitcode.com/GitHub_Trending/la/langchaingo创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考