langchain/qdrant 集成指南在 LangChain.js 中使用 Qdrant 向量数据库【免费下载链接】langchainjsThe agent engineering platform项目地址: https://gitcode.com/GitHub_Trending/la/langchainjs本篇指南以langchainjs仓库中 langchain/qdrant 包 为对象系统讲解该 LangChain.js 官方 Qdrant 向量数据库集成包的安装方式、核心 API 能力与配置参数并结合仓库源码与测试用例剖析其底层实现原理同时完整覆盖该包的本地开发、构建、测试与发布工作流。读完本文你将掌握如何在自己的应用中完成 Qdrant 的安装接入、向量写入与相似度检索以及如何以贡献者身份在该仓库中开发、验证并扩展langchain/qdrant。一、包定位与核心能力langchain/qdrant是 LangChain.js 官方维护的 Qdrant 向量数据库集成包。Qdrant 是一个高性能向量搜索引擎与相似度检索引擎而本包通过 LangChain.js 统一的VectorStore抽象将 Qdrant 无缝接入到 RAG、语义搜索、文档问答等应用中。从源码结构看该包的导出全部集中在 src/index.ts它只做了一件事export * from ./vectorstores.js即对外暴露 vectorstores.ts 中定义的QdrantVectorStore类及配套类型。包的核心能力包括写入addDocuments/addVectors将文档及其向量写入 Qdrant 集合检索similaritySearch、similaritySearchVectorWithScore、maxMarginalRelevanceSearchMMR 最大边际相关性检索删除delete支持按 ID 或按过滤器批量删除集合管理ensureCollection集合不存在时自动创建工厂方法fromTexts、fromDocuments、fromExistingCollection三种快速初始化路径。依赖方面包在运行时仅依赖qdrant/js-client-rest版本^1.19.0并将langchain/core作为 peerDependency相关声明可见 package.json。二、安装与前置要求在你的 LangChain.js 项目中安装该集成包npm install langchain/qdrant由于langchain/core是 peerDependency通常需要一并安装langchain/core与具体的 Embeddings 模型包如 OpenAI、Anthropic 等才能完整运行。此外根据 package.json 中的engines字段该包要求Node.js 20。三、核心 API 与配置参数详解QdrantVectorStore的构造函数签名为constructor(embeddings, args)其中args的类型是QdrantLibArgs其字段定义见 vectorstores.ts参数类型说明默认值clientQdrantClient直接传入已配置好的 Qdrant 客户端实例无与url二选一urlstringQdrant 服务地址环境变量QDRANT_URLapiKeystringQdrant API Key环境变量QDRANT_API_KEYcollectionNamestring目标集合名称documentscollectionConfigQdrantSchemas[CreateCollection]创建集合时的配置向量维度、距离度量等自动探测维度 Cosine距离customPayloadRecordstring, any[]附加到每个点的自定义载荷数组与文档一一对应无contentPayloadKeystring存储文档正文的 payload 键名contentmetadataPayloadKeystring存储文档元数据的 payload 键名metadata构造函数内部vectorstores.ts的解析逻辑如下url与apiKey优先取构造参数其次回退到环境变量QDRANT_URL/QDRANT_API_KEY若既未传入client也未解析到url直接抛出Qdrant client or url address must be set.若传入了client则直接复用否则内部new QdrantClient({ url, apiKey })同时lc_secrets声明了apiKey与url对应的环境变量名这使得该 store 可以配合 LangChain 的序列化/追踪机制安全地处理密钥。连接方式一URL API Keyimport { QdrantVectorStore } from langchain/qdrant; import { OpenAIEmbeddings } from langchain/openai; const store new QdrantVectorStore(new OpenAIEmbeddings(), { url: http://localhost:6333, apiKey: process.env.QDRANT_API_KEY, collectionName: my_documents, });连接方式二直接传入 QdrantClientimport { QdrantClient } from qdrant/js-client-rest; import { QdrantVectorStore } from langchain/qdrant; const client new QdrantClient({ url: process.env.QDRANT_URL, apiKey: process.env.QDRANT_API_KEY, }); const store new QdrantVectorStore(new OpenAIEmbeddings(), { client, collectionName: my_documents, });连接方式三通过环境变量// 设置环境变量后即可省略 url / apiKey // export QDRANT_URLhttp://localhost:6333 // export QDRANT_API_KEYyour-key const store new QdrantVectorStore(new OpenAIEmbeddings(), { collectionName: my_documents, });四、文档写入从文本到 Qdrant 点4.1 addDocuments 的完整链路addDocuments(documents, documentOptions?)的执行流程vectorstores.ts为提取所有文档的pageContent文本调用this.embeddings.embedDocuments(texts)批量生成向量将向量与文档一起交给addVectors。addVectorsvectorstores.ts在写入前会先调用ensureCollection()确保集合存在随后将每个向量构造成 Qdrant 的 pointconst points vectors.map((embedding, idx) ({ id: documents[idx].id ?? documentOptions?.ids?.[idx] ?? uuid(), vector: embedding, payload: { [this.contentPayloadKey]: documents[idx].pageContent, [this.metadataPayloadKey]: documents[idx].metadata, customPayload: documentOptions?.customPayload?.[idx], }, })); await this.client.upsert(this.collectionName, { wait: true, points });关键细节Point ID 优先级Document.iddocumentOptions.ids[idx] 自动生成的uuid()来自langchain/core/utils/uuid同步等待upsert使用wait: true确保写入落盘后才返回保证后续检索的强一致性错误包装写入失败时会将 HTTP 状态码与错误消息包装成统一Error抛出自定义载荷customPayload数组与文档一一对应可写入检索时不参与向量比较、但用于过滤的额外业务字段。4.2 三个工厂方法工厂方法适用场景行为fromTexts(texts, metadatas, embeddings, dbConfig)从纯文本数组快速初始化逐条构造Document并调用fromDocumentsfromDocuments(docs, embeddings, dbConfig)从Document数组初始化构造 store 实例并写入全部文档fromExistingCollection(embeddings, dbConfig)连接已存在的集合只做ensureCollection不写入任何文档其中fromDocumentsvectorstores.ts在dbConfig携带customPayload时会自动将其作为documentOptions传入addDocuments。集成测试 vectorstores.int.test.ts 演示了用fromDocuments配合显式QdrantClient、使用与默认不同维度384 维的 embedding 创建独立集合的用法。五、相似度检索向量查询与 MMR5.1 similaritySearchVectorWithScore这是所有相似度检索的底层实现vectorstores.tsconst results ( await this.client.query(this.collectionName, { query, limit: k, filter, with_payload: [this.metadataPayloadKey, this.contentPayloadKey], with_vector: false, }) ).points;其要点通过 Qdrant REST 客户端的query接口执行近邻检索limit为返回条数k仅回传content与metadata两个 payload 字段with_vector: false不返回向量降低带宽开销结果被映射为[Document, number][]即每个文档附带相似度得分scoreDocument.id取自 Qdrant point 的id检索前同样会调用ensureCollection()避免集合缺失时报错。单元测试 vectorstores.test.ts 用 mock client 验证了「写入后调用similaritySearch」的完整调用链集成测试则验证了写入后能精确检索回原文档含id、metadata、pageContent完全一致。5.2 MMR 最大边际相关性检索maxMarginalRelevanceSearch(query, options)vectorstores.ts在相似度的基础上引入多样性避免返回内容高度重复的结果const results ( await this.client.query(this.collectionName, { query: { nearest: queryEmbedding, mmr: { diversity: options.lambda ?? null, candidates_limit: options?.fetchK ?? 20, }, }, limit: options.k, filter: options?.filter, with_payload: [this.metadataPayloadKey, this.contentPayloadKey], with_vector: true, }) ).points;MMR 是 Qdrant 服务端原生支持的检索模式本包通过query.nearest query.mmr的组合直接透传k最终返回的文档数量fetchK先取多少个候选再执行 MMR 重排默认20lambda0~1 之间控制多样性程度0对应最大多样性1对应最小多样性最接近纯相似度不传时为null与普通检索不同MMR 需要with_vector: true回传向量供服务端计算多样性。单元测试 vectorstores.test.ts 精确断言了 MMR 模式下client.query的入参结构集成测试 vectorstores.int.test.ts 验证了在语义差异明显的文档集上执行maxMarginalRelevanceSearch能返回预期的多样结果。5.3 过滤与删除QdrantVectorStore的FilterType直接复用了 Qdrant 的过滤类型QdrantSchemas[Filter]因此可以构造任意复杂的条件过滤查询字段条件、must / should / must_not 组合等filter参数被原样透传给服务端。delete(params)vectorstores.ts支持两种删除方式且二者互斥ids与filter只能选其一否则抛错按 ID 删除{ ids: string[], shardKey? }内部按每批 1000 个 ID 分批调用 Qdrant 的delete接口按过滤器删除{ filter: object, shardKey? }一次调用删除所有匹配的点。两种方式都使用wait: true与ordering: weak确保删除即时生效。六、集合自动创建机制ensureCollection()vectorstores.ts是写入与检索前都会执行的自愈逻辑const response await this.client.getCollections(); const collectionNames response.collections.map((c) c.name); if (!collectionNames.includes(this.collectionName)) { const collectionConfig this.collectionConfig ?? { vectors: { size: (await this.embeddings.embedQuery(test)).length, distance: Cosine, }, }; await this.client.createCollection(this.collectionName, collectionConfig); }若目标集合不存在它会调用当前 Embeddings 实例对test做一次查询嵌入自动探测向量维度默认使用Cosine 余弦距离作为相似度度量调用createCollection创建集合。如果你对维度、距离度量如Dot、Euclid或量化配置有特殊要求可通过collectionConfig参数传入完整的 QdrantCreateCollection配置覆盖默认行为避免自动创建的默认配置与模型维度不匹配。七、本地开发与贡献指南7.1 安装依赖该包属于 pnpm workspace 的一部分在仓库根目录执行pnpm install按仓库约定见 AGENTS.md建议先构建核心包再开发依赖它的集成包pnpm --filter langchain/core build7.2 构建包在包目录内构建pnpm build或从仓库根目录按 filter 构建这也是 README 推荐的等价写法pnpm build --filter langchain/qdrant构建由 tsdown.config.ts 驱动入口为./src/index.ts并通过cjsCompatPlugin同步产出 ESM 与 CJS 双格式产物见 package.json 中exports的import/require映射。7.3 运行测试该包遵循仓库统一的测试命名约定单元测试以.test.ts结尾位于src/tests/下不依赖外部服务集成测试以.int.test.ts结尾需要可用的 Qdrant 实例。# 运行单元测试 pnpm test # 运行集成测试需要 Qdrant 服务与 QDRANT_URL 等环境变量 pnpm test:int本仓库中现成的测试文件分别是 vectorstores.test.tsmock client FakeEmbeddings 的单元测试覆盖写入、customPayload、MMR 参数与 vectorstores.int.test.ts真实 Qdrant 实例上的端到端验证默认连接http://localhost:6333也支持QDRANT_URL、QDRANT_API_KEY、QDRANT_COLLECTION环境变量。如果你本机通过 Docker 启动了 Qdrant直接运行pnpm test:int即可复现上述集成测试。7.4 代码规范检查开发完成后运行 lint 与格式化保证代码符合仓库标准pnpm lint pnpm formatlint会依次执行 ESLint 检查与 dpdm 循环依赖检测见 package.json 的 scripts。7.5 新增导出入口如果新增了需要对外暴露的模块在src/index.ts中import并re-export或在 package.json 的exports字段中登记新的入口重新执行pnpm build生成新的 entrypoint 产物。八、小结langchain/qdrant以一个轻量的QdrantVectorStore类将 Qdrant 的能力完整封装进 LangChain.js 的VectorStore生态自动建集合、向量写入、相似度检索、MMR 多样检索、按 ID/过滤器删除、三种工厂方法一应俱全。无论你是想快速接入现有 Qdrant 集合还是希望为集成包的开发贡献力量都可以从 vectorstores.ts 的源码和 vectorstores.int.test.ts 的测试入手结合本文的配置参数表与实践示例快速落地你的语义检索应用。【免费下载链接】langchainjsThe agent engineering platform项目地址: https://gitcode.com/GitHub_Trending/la/langchainjs创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
@langchain/qdrant 集成指南：在 LangChain.js 中使用 Qdrant 向量数据库
langchain/qdrant 集成指南在 LangChain.js 中使用 Qdrant 向量数据库【免费下载链接】langchainjsThe agent engineering platform项目地址: https://gitcode.com/GitHub_Trending/la/langchainjs本篇指南以langchainjs仓库中 langchain/qdrant 包 为对象系统讲解该 LangChain.js 官方 Qdrant 向量数据库集成包的安装方式、核心 API 能力与配置参数并结合仓库源码与测试用例剖析其底层实现原理同时完整覆盖该包的本地开发、构建、测试与发布工作流。读完本文你将掌握如何在自己的应用中完成 Qdrant 的安装接入、向量写入与相似度检索以及如何以贡献者身份在该仓库中开发、验证并扩展langchain/qdrant。一、包定位与核心能力langchain/qdrant是 LangChain.js 官方维护的 Qdrant 向量数据库集成包。Qdrant 是一个高性能向量搜索引擎与相似度检索引擎而本包通过 LangChain.js 统一的VectorStore抽象将 Qdrant 无缝接入到 RAG、语义搜索、文档问答等应用中。从源码结构看该包的导出全部集中在 src/index.ts它只做了一件事export * from ./vectorstores.js即对外暴露 vectorstores.ts 中定义的QdrantVectorStore类及配套类型。包的核心能力包括写入addDocuments/addVectors将文档及其向量写入 Qdrant 集合检索similaritySearch、similaritySearchVectorWithScore、maxMarginalRelevanceSearchMMR 最大边际相关性检索删除delete支持按 ID 或按过滤器批量删除集合管理ensureCollection集合不存在时自动创建工厂方法fromTexts、fromDocuments、fromExistingCollection三种快速初始化路径。依赖方面包在运行时仅依赖qdrant/js-client-rest版本^1.19.0并将langchain/core作为 peerDependency相关声明可见 package.json。二、安装与前置要求在你的 LangChain.js 项目中安装该集成包npm install langchain/qdrant由于langchain/core是 peerDependency通常需要一并安装langchain/core与具体的 Embeddings 模型包如 OpenAI、Anthropic 等才能完整运行。此外根据 package.json 中的engines字段该包要求Node.js 20。三、核心 API 与配置参数详解QdrantVectorStore的构造函数签名为constructor(embeddings, args)其中args的类型是QdrantLibArgs其字段定义见 vectorstores.ts参数类型说明默认值clientQdrantClient直接传入已配置好的 Qdrant 客户端实例无与url二选一urlstringQdrant 服务地址环境变量QDRANT_URLapiKeystringQdrant API Key环境变量QDRANT_API_KEYcollectionNamestring目标集合名称documentscollectionConfigQdrantSchemas[CreateCollection]创建集合时的配置向量维度、距离度量等自动探测维度 Cosine距离customPayloadRecordstring, any[]附加到每个点的自定义载荷数组与文档一一对应无contentPayloadKeystring存储文档正文的 payload 键名contentmetadataPayloadKeystring存储文档元数据的 payload 键名metadata构造函数内部vectorstores.ts的解析逻辑如下url与apiKey优先取构造参数其次回退到环境变量QDRANT_URL/QDRANT_API_KEY若既未传入client也未解析到url直接抛出Qdrant client or url address must be set.若传入了client则直接复用否则内部new QdrantClient({ url, apiKey })同时lc_secrets声明了apiKey与url对应的环境变量名这使得该 store 可以配合 LangChain 的序列化/追踪机制安全地处理密钥。连接方式一URL API Keyimport { QdrantVectorStore } from langchain/qdrant; import { OpenAIEmbeddings } from langchain/openai; const store new QdrantVectorStore(new OpenAIEmbeddings(), { url: http://localhost:6333, apiKey: process.env.QDRANT_API_KEY, collectionName: my_documents, });连接方式二直接传入 QdrantClientimport { QdrantClient } from qdrant/js-client-rest; import { QdrantVectorStore } from langchain/qdrant; const client new QdrantClient({ url: process.env.QDRANT_URL, apiKey: process.env.QDRANT_API_KEY, }); const store new QdrantVectorStore(new OpenAIEmbeddings(), { client, collectionName: my_documents, });连接方式三通过环境变量// 设置环境变量后即可省略 url / apiKey // export QDRANT_URLhttp://localhost:6333 // export QDRANT_API_KEYyour-key const store new QdrantVectorStore(new OpenAIEmbeddings(), { collectionName: my_documents, });四、文档写入从文本到 Qdrant 点4.1 addDocuments 的完整链路addDocuments(documents, documentOptions?)的执行流程vectorstores.ts为提取所有文档的pageContent文本调用this.embeddings.embedDocuments(texts)批量生成向量将向量与文档一起交给addVectors。addVectorsvectorstores.ts在写入前会先调用ensureCollection()确保集合存在随后将每个向量构造成 Qdrant 的 pointconst points vectors.map((embedding, idx) ({ id: documents[idx].id ?? documentOptions?.ids?.[idx] ?? uuid(), vector: embedding, payload: { [this.contentPayloadKey]: documents[idx].pageContent, [this.metadataPayloadKey]: documents[idx].metadata, customPayload: documentOptions?.customPayload?.[idx], }, })); await this.client.upsert(this.collectionName, { wait: true, points });关键细节Point ID 优先级Document.iddocumentOptions.ids[idx] 自动生成的uuid()来自langchain/core/utils/uuid同步等待upsert使用wait: true确保写入落盘后才返回保证后续检索的强一致性错误包装写入失败时会将 HTTP 状态码与错误消息包装成统一Error抛出自定义载荷customPayload数组与文档一一对应可写入检索时不参与向量比较、但用于过滤的额外业务字段。4.2 三个工厂方法工厂方法适用场景行为fromTexts(texts, metadatas, embeddings, dbConfig)从纯文本数组快速初始化逐条构造Document并调用fromDocumentsfromDocuments(docs, embeddings, dbConfig)从Document数组初始化构造 store 实例并写入全部文档fromExistingCollection(embeddings, dbConfig)连接已存在的集合只做ensureCollection不写入任何文档其中fromDocumentsvectorstores.ts在dbConfig携带customPayload时会自动将其作为documentOptions传入addDocuments。集成测试 vectorstores.int.test.ts 演示了用fromDocuments配合显式QdrantClient、使用与默认不同维度384 维的 embedding 创建独立集合的用法。五、相似度检索向量查询与 MMR5.1 similaritySearchVectorWithScore这是所有相似度检索的底层实现vectorstores.tsconst results ( await this.client.query(this.collectionName, { query, limit: k, filter, with_payload: [this.metadataPayloadKey, this.contentPayloadKey], with_vector: false, }) ).points;其要点通过 Qdrant REST 客户端的query接口执行近邻检索limit为返回条数k仅回传content与metadata两个 payload 字段with_vector: false不返回向量降低带宽开销结果被映射为[Document, number][]即每个文档附带相似度得分scoreDocument.id取自 Qdrant point 的id检索前同样会调用ensureCollection()避免集合缺失时报错。单元测试 vectorstores.test.ts 用 mock client 验证了「写入后调用similaritySearch」的完整调用链集成测试则验证了写入后能精确检索回原文档含id、metadata、pageContent完全一致。5.2 MMR 最大边际相关性检索maxMarginalRelevanceSearch(query, options)vectorstores.ts在相似度的基础上引入多样性避免返回内容高度重复的结果const results ( await this.client.query(this.collectionName, { query: { nearest: queryEmbedding, mmr: { diversity: options.lambda ?? null, candidates_limit: options?.fetchK ?? 20, }, }, limit: options.k, filter: options?.filter, with_payload: [this.metadataPayloadKey, this.contentPayloadKey], with_vector: true, }) ).points;MMR 是 Qdrant 服务端原生支持的检索模式本包通过query.nearest query.mmr的组合直接透传k最终返回的文档数量fetchK先取多少个候选再执行 MMR 重排默认20lambda0~1 之间控制多样性程度0对应最大多样性1对应最小多样性最接近纯相似度不传时为null与普通检索不同MMR 需要with_vector: true回传向量供服务端计算多样性。单元测试 vectorstores.test.ts 精确断言了 MMR 模式下client.query的入参结构集成测试 vectorstores.int.test.ts 验证了在语义差异明显的文档集上执行maxMarginalRelevanceSearch能返回预期的多样结果。5.3 过滤与删除QdrantVectorStore的FilterType直接复用了 Qdrant 的过滤类型QdrantSchemas[Filter]因此可以构造任意复杂的条件过滤查询字段条件、must / should / must_not 组合等filter参数被原样透传给服务端。delete(params)vectorstores.ts支持两种删除方式且二者互斥ids与filter只能选其一否则抛错按 ID 删除{ ids: string[], shardKey? }内部按每批 1000 个 ID 分批调用 Qdrant 的delete接口按过滤器删除{ filter: object, shardKey? }一次调用删除所有匹配的点。两种方式都使用wait: true与ordering: weak确保删除即时生效。六、集合自动创建机制ensureCollection()vectorstores.ts是写入与检索前都会执行的自愈逻辑const response await this.client.getCollections(); const collectionNames response.collections.map((c) c.name); if (!collectionNames.includes(this.collectionName)) { const collectionConfig this.collectionConfig ?? { vectors: { size: (await this.embeddings.embedQuery(test)).length, distance: Cosine, }, }; await this.client.createCollection(this.collectionName, collectionConfig); }若目标集合不存在它会调用当前 Embeddings 实例对test做一次查询嵌入自动探测向量维度默认使用Cosine 余弦距离作为相似度度量调用createCollection创建集合。如果你对维度、距离度量如Dot、Euclid或量化配置有特殊要求可通过collectionConfig参数传入完整的 QdrantCreateCollection配置覆盖默认行为避免自动创建的默认配置与模型维度不匹配。七、本地开发与贡献指南7.1 安装依赖该包属于 pnpm workspace 的一部分在仓库根目录执行pnpm install按仓库约定见 AGENTS.md建议先构建核心包再开发依赖它的集成包pnpm --filter langchain/core build7.2 构建包在包目录内构建pnpm build或从仓库根目录按 filter 构建这也是 README 推荐的等价写法pnpm build --filter langchain/qdrant构建由 tsdown.config.ts 驱动入口为./src/index.ts并通过cjsCompatPlugin同步产出 ESM 与 CJS 双格式产物见 package.json 中exports的import/require映射。7.3 运行测试该包遵循仓库统一的测试命名约定单元测试以.test.ts结尾位于src/tests/下不依赖外部服务集成测试以.int.test.ts结尾需要可用的 Qdrant 实例。# 运行单元测试 pnpm test # 运行集成测试需要 Qdrant 服务与 QDRANT_URL 等环境变量 pnpm test:int本仓库中现成的测试文件分别是 vectorstores.test.tsmock client FakeEmbeddings 的单元测试覆盖写入、customPayload、MMR 参数与 vectorstores.int.test.ts真实 Qdrant 实例上的端到端验证默认连接http://localhost:6333也支持QDRANT_URL、QDRANT_API_KEY、QDRANT_COLLECTION环境变量。如果你本机通过 Docker 启动了 Qdrant直接运行pnpm test:int即可复现上述集成测试。7.4 代码规范检查开发完成后运行 lint 与格式化保证代码符合仓库标准pnpm lint pnpm formatlint会依次执行 ESLint 检查与 dpdm 循环依赖检测见 package.json 的 scripts。7.5 新增导出入口如果新增了需要对外暴露的模块在src/index.ts中import并re-export或在 package.json 的exports字段中登记新的入口重新执行pnpm build生成新的 entrypoint 产物。八、小结langchain/qdrant以一个轻量的QdrantVectorStore类将 Qdrant 的能力完整封装进 LangChain.js 的VectorStore生态自动建集合、向量写入、相似度检索、MMR 多样检索、按 ID/过滤器删除、三种工厂方法一应俱全。无论你是想快速接入现有 Qdrant 集合还是希望为集成包的开发贡献力量都可以从 vectorstores.ts 的源码和 vectorstores.int.test.ts 的测试入手结合本文的配置参数表与实践示例快速落地你的语义检索应用。【免费下载链接】langchainjsThe agent engineering platform项目地址: https://gitcode.com/GitHub_Trending/la/langchainjs创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考