LangChain.js 集成指南使用 langchain/weaviate 构建 Weaviate 向量存储与检索应用【免费下载链接】langchainjsThe agent engineering platform项目地址: https://gitcode.com/GitHub_Trending/la/langchainjs导读langchain/weaviate是 LangChain.js 官方提供的 Weaviate 向量数据库集成包它在weaviate-clientSDK 之上封装了标准化的VectorStore接口让开发者可以用一套统一 API 完成文档写入、相似度检索、混合检索Hybrid Search、MMR 多样性检索与 RAG 生成式搜索。阅读本文后你将掌握该包的安装配置、客户端接入、WeaviateStore全量 API 用法、结构化查询过滤以及参与该包二次开发的标准工作流。一、包概览与定位langchain/weaviate位于仓库 libs/providers/langchain-weaviate 目录下核心职责有两部分Vectorstore在 src/vectorstores.ts 中实现了WeaviateStore类继承自langchain/core/vectorstores的VectorStore基类提供与 LangChain.js 生态其他向量库完全一致的交互方式结构化查询翻译器在 src/translator.ts 中实现了WeaviateTranslator用于将 LLM 生成的 Structured Query 翻译为 Weaviate 原生过滤语法供SelfQueryRetriever使用。包入口 src/index.ts 同时导出了这两个模块。从 package.json 可以看到该包以weaviate-client版本^3.14.0为直接依赖以langchain/core为 peer 依赖同时以langchain/openai作为开发依赖用于集成测试中的 Embeddings 模型。包版本为1.1.0要求 Node.js 环境不低于 20。二、安装与初始化2.1 安装依赖包在项目中安装langchain/weaviate及其核心依赖npm install langchain/weaviate langchain/core由于向量化需要嵌入模型README 建议同时安装langchain/openai对应 OpenAI Embeddings 模型实际开发中也可替换为仓库内其他 provider如 langchain-google-genai、langchain-anthropic 等提供的 Embeddings 实现npm install langchain/openai2.2 配置环境变量与创建 Weaviate 客户端README 推荐的连接方式是使用weaviate-clientSDK 自行创建客户端再注入WeaviateStore。先设置环境变量或通过 client 对象直接传入export WEAVIATE_SCHEME export WEAVIATE_HOST export WEAVIATE_API_KEY说明WEAVIATE_SCHEME通常为httpsWEAVIATE_HOST为你的 Weaviate 实例地址如localhost:8080或云实例域名WEAVIATE_API_KEY为 API Key。三者留空时代码中的兜底默认值分别是https、localhost、default。创建客户端的参考代码如下README 原样保留其中as any的写法是为了规避weaviate-clientSDK 的一个 TypeScript 类型声明问题import weaviate, { ApiKey } from weaviate-client; import { WeaviateStore } from langchain/weaviate; // Weaviate SDK has a TypeScript issue so we must do this. const client (weaviate as any).client({ scheme: process.env.WEAVIATE_SCHEME || https, host: process.env.WEAVIATE_HOST || localhost, apiKey: new ApiKey(process.env.WEAVIATE_API_KEY || default), });需要说明的是这是 README 中使用的兼容写法。在当前仓库的集成测试中weaviate-client的 v3 SDK 还提供了更现代的工厂方法二者等价可任选其一本地实例await weaviate.connectToLocal({ headers: { ... } })云实例await weaviate.connectToWeaviateCloud(WEAVIATE_URL, { authCredentials: new weaviate.ApiKey(WEAVIATE_API_KEY), headers: {...} })。可参考 vectorstores.int.test.ts 中的beforeAll写法。三、WeaviateStore 快速上手写入与基础检索3.1 从文本列表创建存储并写入WeaviateStore.fromTexts是 README 给出的最快上手路径它会将文本数组与元数据数组配对构建Document调用 Embeddings 生成向量后批量写入 Weaviate// Create a store and fill it with some texts metadata await WeaviateStore.fromTexts( [hello world, hi there, how are you, bye now], [{ foo: bar }, { foo: baz }, { foo: qux }, { foo: bar }], new OpenAIEmbeddings(), { client, indexName: Test, textKey: text, metadataKeys: [foo], } );各参数含义如下参数类型说明textsstring[]待写入的文本内容数组metadatasobject \| object[]与 texts 一一对应的元数据也可传单个对象共享给所有文本embeddingsEmbeddingsInterface文本向量化模型实例clientWeaviateClientweaviate-client 客户端indexNamestringWeaviate 中的 collection类名称源码注释要求必须以大写字母开头textKeystring存储正文所用的属性名默认textmetadataKeysstring[]需要参与检索返回的元数据键集合默认仅返回textKey3.2 其他静态工厂方法在 vectorstores.ts 中WeaviateStore提供了四条创建路径按使用场景区分fromTexts(texts, metadatas, embeddings, args)从文本 元数据数组构建并写入内部转成Document后走fromDocumentsfromDocuments(docs, embeddings, args)从Document[]构建并写入适合已有Document管线的场景fromExistingIndex(embeddings, args)仅绑定一个已存在的 Weaviate collection不做任何写入适合连接既有数据initialize(embeddings, config)底层初始化方法先检查client.collections.exists(indexName)collection 不存在时按优先级自动创建显式传入jsonSchema则调用createFromJson否则有schema调用create都没有则用简化配置create({ name })创建若传了tenant创建时会自动开启多租户multiTenancy并启用autoTenantCreation。3.3 基础相似度检索写入后即可通过VectorStore基类提供的similaritySearch(query, k, filter?)进行检索。在 vectorstores.int.test.ts 中核心测试验证了写入 4 条文本后执行store.similaritySearch(hello world, 1)能精确命中pageContent: hello world、metadata: { foo: bar }的文档同时验证了结合过滤器的检索结果。检索底层实现在similaritySearchVectorWithScoreAndEmbedding通过collection.query.nearVector(query, ...)执行向量近邻查询请求returnMetadata: [distance, score]返回文档、距离、得分及向量四元组。similaritySearchVectorWithScore则在此基础上丢弃向量只保留[Document, score]元组。四、WeaviateLibArgs 配置项详解与元数据扁平化4.1 完整配置项WeaviateStore构造函数的第二参数类型为WeaviateLibArgs定义于 vectorstores.ts 顶部除上表外还有两个高级项参数类型说明tenantstring指定多租户multi-tenancy租户名一旦指定写入、检索、删除都会通过collection.withTenant(tenant)限定到该租户integration 测试中有专门用例schemaCollectionConfigCreateweaviate-client 的类型化 collection 配置initialize时用于自动建库client.collections.create(schema)jsonSchemaWeaviateClass原生 Weaviate JSON schema与 REST API 返回结构一致直接传给client.collections.createFromJson()当schema与jsonSchema同时给出时jsonSchema优先indexName的取值优先级为显式indexNameschema.namejsonSchema.class源码注释特别提醒这里的class是 Weaviate 遗留的 collection 标识字段名并非 JSON Schema 标准关键字。另外metadataKeys中不合法的键会被过滤并打印警告——因为queryAttrs必须满足 GraphQL Name 规范正则^[_A-Za-z][_0-9A-Za-z]*$例如含冒号、连字符的键会被跳过仅用于写入而不会在查询返回中展开。4.2 元数据扁平化机制Weaviate 原生数据模型不支持任意深度的嵌套对象因此源码提供了导出的工具函数flattenObjectForWeaviate它递归地把嵌套对象按键名拼接展开如deep.deeppdeep.string→deep_deepdeep_string并将键中所有非字母数字下划线字符替换为_如some:colon→some_colon。数组仅保留「全为同类型原始值」的情况空数组与异构数组会被丢弃。对应行为由单元测试 vectorstores.test.ts 中的flattenObjectForWeaviate快照用例完整锁定integration 测试也验证了深层元数据deep_string、deep_deepdeep_string可被写入并按扁平化后的键过滤查询。五、高级检索能力5.1 混合检索 hybridSearchhybridSearch(query, options?)同时执行向量检索与 BM25F 关键词检索并融合两组结果对语义理解与精确关键词匹配都有需求时非常实用实现见 vectorstores.ts。其行为要点未显式提供options.vector时内部会用embeddings.embedQuery(query)自动生成查询向量options.filter与options.filters均被接受且filters优先默认请求returnMetadata: [score, ...]支持透传 weaviate-client 的HybridOptions如limit、alpha向量与关键词结果的权重平衡、autoLimit、targetVector命名向量、rerank重排序等。在 hybridsearch.int.test.ts 中有多个真实用例指定limit: 1的基础混合检索基于命名向量targetVector: [title]用葡萄牙语查询命中英文语义结果配置 Cohere reranker 后按title属性重排结果元数据中出现rerankScore以及同时提供alpha、autoLimit、自定义vector与returnMetadata: [explainScore, creationTime]的组合用法。5.2 最大边际相关性检索 maxMarginalRelevanceSearchmaxMarginalRelevanceSearch(query, options)在相似度与多样性之间取平衡适合摘要生成、问答去重等场景。核心参数k最终返回文档数fetchK先取回的候选数默认20lambda0~1 之间的多样性权重0对应最大多样性、1对应最小多样性即纯相似度默认0.5filter可选的 WeaviateFilterValue过滤器。实现上先取回fetchK条带向量的结果再调用langchain/core/utils/math的maximalMarginalRelevance做二次挑选见 vectorstores.ts对应 integration 用例maxMarginalRelevanceSearch。5.3 生成式搜索 generateRAGgenerate(query, generate, options?)是 Weaviate 的 Retrieval Augmented Generation 能力先执行混合检索再把命中文档与提示词一并交给 Weaviate 上配置的生成模型如 OpenAI返回带生成结果的文档。返回的是WeaviateDocument比普通Document多出三个字段generated模型生成的文本对应data.generative.textvectors文档的向量数据additional查询附加元数据。generate.int.test.ts 中演示了完整用法collection schema 需配置generative: weaviate.configure.generative.openAI()然后传入singlePrompt: { prompt: Translate this into German: {title} }返回结果中generated字段即为生成内容。5.4 删除操作 deletedelete({ ids?, filter? })支持两种方式按 ID 批量删除collection.filter.byId().containsAny(ids)或按过滤器删除二者必填其一否则抛错。integration 测试验证了按foo属性过滤删除后对应文档不再被检索到。多租户模式下删除同样会带上withTenant。六、结构化查询过滤与 SelfQueryRetrievertranslator.ts 中的WeaviateTranslator继承langchain/core/structured_query的BaseTranslator将 LLM 生成的结构化查询编译为 Weaviate 原生FilterValue。它支持逻辑操作符And、Or对应Operators.and / or比较操作符Equal、NotEqual、LessThan、LessThanEqual、GreaterThan、GreaterThanEqual值类型推断字符串值会被自动识别为 string / int / float 并做相应转换mergeFilters提供and/or/replace三种策略将默认过滤器与模型生成的过滤器合并。翻译器还支持FilterValue作为WeaviateStore.FilterType因此similaritySearch、hybridSearch、maxMarginalRelevanceSearch等方法的filter参数可以直接接受collection.filter.byProperty(...)构造的原生过滤器integration 测试中大量使用Filters.and(collection.filter.byProperty(foo).equal(baz))形式。配合自查询检索器的典型用法源码 JSDoc 示例const selfQueryRetriever new SelfQueryRetriever({ llm: new ChatOpenAI({ model: gpt-4o-mini }), vectorStore: new WeaviateStore(), documentContents: Brief summary of a movie, attributeInfo: [], structuredQueryTranslator: new WeaviateTranslator(), }); const relevantDocuments await selfQueryRetriever.getRelevantDocuments( Which movies are rated higher than 8.5?, );七、包的开发与测试工作流README 的 Development 章节面向希望参与langchain/weaviate二次开发或本地调试的开发者完整流程如下。7.1 安装依赖与构建该仓库使用 pnpm workspace turbo 管理在仓库根目录执行pnpm install构建包包内目录执行pnpm build或从仓库根目录按 filter 构建pnpm build --filter langchain/weaviate构建由 tsdown 完成见 package.json 的build:compile脚本产物输出到dist/同时提供 ESMimport与 CJSrequire双入口及对应类型声明。7.2 测试规范与运行测试文件统一放在src/下的tests/目录中命名约定单元测试以.test.ts结尾mock 客户端不依赖真实 Weaviate 实例集成测试以.int.test.ts结尾需要真实 Weaviate 与 OpenAI API Key。pnpm test # 运行单元测试vitest run pnpm test:int # 运行集成测试vitest --mode int集成测试通过dotenv加载环境变量WEAVIATE_URL值为local时连接本地实例否则走connectToWeaviateCloud连接云实例参见 vectorstores.int.test.ts。单元测试使用langchain/core/utils/testing的FakeEmbeddings与 mock 客户端覆盖了集成头注册、schema/jsonSchema 建库优先级、hybridSearch/generate 的 filter 转发、元数据扁平化等关键行为见 vectorstores.test.ts。7.3 Lint 与格式化pnpm lint pnpm format其中lint由 ESLint 与 dpdm 循环依赖检查两部分组成lint:eslintlint:dpdmformat使用 Prettier 自动格式化src目录。7.4 新增导出入口若新增需要对外导出的文件有两种方式在 src/index.ts 中 import 并 re-export在 package.json 的exports字段中新增入口然后运行pnpm build重新生成构建产物。八、总结langchain/weaviate通过WeaviateStore把 Weaviate 的向量检索、混合检索、MMR 与生成式 RAG 能力统一收敛到 LangChain.js 的VectorStore接口之下配合WeaviateTranslator还可以让 LLM 自主构造元数据过滤条件。对于需要在 LangChain.js 生态中接入 Weaviate 的开发者建议按「安装 → 创建客户端 →fromTexts/fromDocuments写入 →similaritySearch/hybridSearch检索 →generate生成」的路径快速落地对包本身的开发与贡献则遵循 README 中的测试命名与构建约定即可。【免费下载链接】langchainjsThe agent engineering platform项目地址: https://gitcode.com/GitHub_Trending/la/langchainjs创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考