Milvus 向量检索 zilliztech/dsh-milvus

Milvus for DSH

Milvus for DSH 让 DSH Desktop 或 Web 智能体在聊天中查看和搜索 Milvus 部署。它支持 Local Milvus 和 Zilliz Cloud、精确实体查找、标量查询、BM25 全文搜索，以及 dense+BM25 混合检索。自然语言 dense 搜索使用 DSH 托管的 embedding 服务商；BM25 完全依赖集合的 Milvus Function schema 运行。

本插件暴露的每个 Milvus 操作都是只读的。插件不会创建集合、插入数据、修改索引或删除任何内容。

环境要求

- DSH Desktop 或 Web 0.2.0-rc.2 或更高版本，且低于 1.0.0
- Node.js 22.19 或更高版本
- 从 DSH 主机可访问的 Milvus HTTP(S) 端点
- 可选：来自受支持 embedding 服务商的 API key，用于 dense 和混合搜索

安装

在 DSH Desktop 中打开 Plugins → Add plugin，输入 @zilliz/dsh-milvus，安装后重启应用。

DSH Web 需要把包安装到 Web 配置档：

dsh plugin --profile web add @zilliz/dsh-milvus
dsh web

如果 dsh 没有全局安装：

npx --yes @deepseek-ai/dsh@latest plugin --profile web add @zilliz/dsh-milvus
npx --yes @deepseek-ai/dsh@latest web

安装或更新插件后，重启 DSH Desktop 或 Web。使用 Web 时刷新浏览器页面。

配置插件

打开 Plugins，选择 @zilliz/dsh-milvus。配置显示在插件详情页。配置顺序与使用 Milvus 的顺序一致：先连接部署，再选择集合，最后只启用你需要的搜索能力。

连接 Milvus

选择 Local Milvus Standalone 或 Zilliz Cloud，然后输入端点和可选的数据库。Local Milvus 通常使用 http://127.0.0.1:19530 和数据库 default。Zilliz Cloud 需要它的 HTTPS 端点和 token。本地部署若启用了认证，选择 Add optional authentication 并输入 token。

保存后，使用 Test connection。卡片会把表单折叠成连接摘要，部署详情不再与集合配置争抢空间。

端点从运行 DSH 的机器解析。Milvus 运行在另一个容器或另一台主机时，请使用从 DSH 主机可访问的地址——不要用 Milvus 容器内部的回环地址。

活动连接在新聊天开始时绑定。修改连接只影响新聊天；不会悄悄把已有聊天切换到另一个部署。

选择集合

Collection 选择器从已连接的 Milvus 数据库填充。选一个集合，DSH 会在 Host 上检查它的字段、索引和 Functions。正常配置流程中不需要手动输入集合名或 schema 字段名。

卡片随后报告四项能力：

- Scalar query 在 schema 检查成功后即可使用。
- BM25 search 在集合有一条有效的 Milvus BM25 Function 路由时即可使用。它不需要外部 API key。
- 语义搜索：映射好嵌入服务商和已发现的 FloatVector 字段后即可使用。
- 混合搜索：BM25 和语义搜索都就绪后，自动变为可用。

需要时启用语义搜索

只有自然语言稠密搜索和混合搜索才需要这一步。BM25 文本搜索不使用外部嵌入服务商。

1. 在语义搜索能力上选择 Enable。
2. 选择服务商和模型，要与集合中已存的向量匹配。
3. 输入服务商 API key。
4. 从所选集合发现的 FloatVector 字段中选一个。
5. 选择 Enable semantic search。

如果已经配置过服务商，直接复用，不用再输 key。字段里存的文档向量，必须是用同一个模型、同一个向量空间生成的。维度对得上，不代表就能兼容；比如 gemini-embedding-001 和 gemini-embedding-2 不能互换。

设置界面支持的模型：

| 服务商 | 模型 | 支持的输出维度 |
| OpenAI | text-embedding-3-small、text-embedding-3-large、text-embedding-ada-002 | 1–1536；1–3072；固定 1536 |
| Google Gemini | gemini-embedding-2、gemini-embedding-001 | 128–3072 |
| Cohere | embed-v4.0、embed-english-v3.0、embed-english-light-v3.0、embed-multilingual-v3.0、embed-multilingual-light-v3.0 | v4：256/512/1024/1536；v3 full：1024；v3 light：384 |
| Voyage AI | voyage-4、voyage-4-large、voyage-4-lite、voyage-code-4、voyage-3.5、voyage-3.5-lite、voyage-code-3、voyage-finance-2、voyage-law-2 | 4/3.5/code-3：256/512/1024/2048；finance/law：1024 |
| Mistral AI | mistral-embed、codestral-embed | 1024；1–3072 |
| Jina AI | jina-embeddings-v5-text-small、jina-embeddings-v5-text-nano、jina-embeddings-v5-omni-small、jina-embeddings-v5-omni-nano、jina-embeddings-v4、jina-embeddings-v3 | small/v3：32/64/128/256/512/768/1024；nano：最高 768；v4：128/256/512/1024/2048 |
| Together AI | intfloat/multilingual-e5-large-instruct | 1024 |

每个服务商列出的第一个模型是推荐默认值。旧模型只在服务商仍提供、且能用来查询该模型向量空间里已有集合时才出现。目录有意排除了已弃用的模型，以及需要专用端点的模型。

表单会禁用所选模型无法产出对应维度的向量字段。维度兼容是必要条件，但不充分：已存的文档向量必须由同一个服务商、同一个模型、同一种任务模式、同一个向量空间生成。

Milvus token 和嵌入 API key 通过只写的 DSH Credentials 保存。它们的值不会存进插件设置，保存后不会回传给浏览器，也不会写进聊天历史。

聊天工具接受自然语言查询文本；它从不询问用户或智能体提供一组浮点数。DSH 在主机上生成查询向量，对照 collection schema 检查维度，然后直接发送给 Milvus。

仅在必要时使用 Advanced settings

Advanced settings 默认折叠。只在需要移除向量映射、在多个经 schema 验证的 BM25 路由中选择，或更改混合排序时才打开。

当 collection 只有一条有效 BM25 路由，且默认 RRF（k=60）适用时，无需 collection 策略。存在多条路由时，从 schema 发现的路由中选择一条；UI 不接受任意文本或稀疏字段名。你也可以选择其他 RRF k，或配置命名的语义/BM25 权重。单个聊天请求中提供的 rerank 参数优先于已保存的默认值。

搜索对 collection 的要求

插件在搜索前检查每个 collection，并报告 dense、BM25 和 hybrid 检索是否就绪。

Dense 搜索需要配置到某个带维度的 FloatVector 字段的绑定。BM25 搜索需要以下全部 collection 事实：

- 一个启用 analyzer 的 VarChar 或 TEXT 输入字段；
- 一个 Milvus BM25 Function，把该文本字段映射到 SparseFloatVector 输出字段；以及
- 该稀疏字段上的 BM25 索引。

当恰好存在一条有效 BM25 路由时，插件自动选择它。如果 collection 有多个 BM25 文本字段，用户必须在请求中指明要搜索哪一个，或保存精确的 collection 策略；智能体不会猜测。仅有 SparseFloatVector 字段而没有 BM25 Function 是不够的，因为插件无法推断是哪个外部稀疏编码器创建了它。

只有当一条 dense 绑定和一条 BM25 路由都就绪时，hybrid 搜索才就绪。如果另一条路由缺失或失败，它绝不会静默回退到单条路由。

在聊天中使用

激活所需的 Milvus 配置档后，开始新聊天。一个有用的首次序列是：

1. “列出我的 Milvus collections。”
2. “描述 documents collection。”
3. “从 documents 获取 ID 10 和 11，返回 id、title 和 source。”
4. “查询 documents 中 year >= 2025 的记录，返回 id 和 title。”
5. “在 documents 中搜索关于 vector indexing 的文档，返回 id、title 和 source。”
6. “使用 BM25 在 documents 中搜索精确短语 HNSW efConstruction，返回 id、title 和 source。”
7. “对 how HNSW indexing works 运行 hybrid 搜索，返回 id 和 title。”
8. “运行 hybrid 搜索，dense 权重 0.7，BM25 权重 0.3。”

智能体应先发现并描述 collection，再使用其字段。当 collection、字段、分区或过滤器有歧义时，它应询问而不是猜测。

可用工具

| 工具 | 用途 |
| milvus_list_collections | 列出聊天所绑定配置档可见的 collections。 |
| milvus_describe_collection | 显示 schema、索引、加载状态，以及 dense/BM25/hybrid 就绪情况或阻塞项。 |
| milvus_get | 按精确的 Int64 或 VarChar 主键取回最多 50 条实体。 |
| milvus_query | 执行有界标量查询，可选过滤条件和分区。 |
| milvus_search | 把自然语言查询文本做嵌入，执行有界稠密检索，可选过滤条件和分区。 |
| milvus_text_search | 通过 schema 已验证的 Milvus BM25 Function 执行有界自然语言 BM25 检索。 |
| milvus_hybrid_search | 合并已配置的稠密与 BM25 两条路径，再用 RRF 或 Weighted 重排融合排名。 |

数据检索工具只返回请求的标量字段。存储的稠密/稀疏向量和生成的查询向量绝不返回给对话。默认结果上限为 10，最大为 50。

稠密检索结果包含 Milvus 距离、向量字段与度量方式、嵌入服务商/模型/维度，以及安全的耗时元数据。不包含 API key、服务商原始错误响应体，也不包含生成的向量。

混合重排属于 milvus_hybrid_search，不是单独的工具：

- 不传重排参数：使用 RRF，k=60；
- 显式 RRF：用户可以另给一个正数 k；
- 显式 Weighted：用户必须同时给出 denseWeight 和 bm25Weight，各自取值 0 到 1，且不能同时为 0。

具名权重可以避免路径顺序出错。如果用户只说「Weighted」却没给数值，智能体会追问这两个权重，而不是猜。检索结果会写明实际生效的重排取值，以及这些取值来自请求、集合策略还是插件默认值。

没有嵌入 key 时会怎样

集合列举、描述、精确 get、标量查询，以及 schema 兼容的 BM25 检索照常可用。稠密检索和混合检索会被拦住，并返回具体的配置结果：

- 没有集合绑定：retrieval_binding_absent；
- 绑定指向不存在的服务商配置档：embedding_profile_absent；
- API key 缺失或不可用：embedding_credential_unavailable。

插件不会退回到对话模型、其他服务商、猜测的向量或标量查询。

隐私与安全

- 稠密检索的查询文本会从 DSH 主机发往绑定中选定的嵌入服务商。
- 生成的向量留在主机内存里，只发给 Milvus。
- Milvus token 和服务商 key 始终留在 DSH Credentials 边界之内。
- 输出字段必须存在于检查过的 schema 中，且必须是标量。
- 过滤条件只能引用从该集合发现的标量字段。
- 精确路径字段可以防止已保存的 BM25 方案悄悄切换路径。如果存在已保存的 schema 指纹，检索 schema 一旦变动，方案就会被拦住，直到重新审核。
- 插件不暴露任何变更、schema、索引、数据库、用户、角色或管理操作。
- 目前不支持外部稀疏编码器、模型/交叉编码器重排、数据写入、自定义嵌入端点，以及手动输入向量。

故障排查

设置卡片不见了

确认包已安装，并在 web 配置档中启用，重启 DSH Web，刷新页面，然后打开 Plugins → @zilliz/dsh-milvus：

dsh plugin --profile web why @zilliz/dsh-milvus

工具提示没有可用的 Milvus 配置档

创建 Milvus 配置档，设为新会话的活跃配置档，再新建一个会话。已有会话保留原来的会话绑定。

Milvus 连接测试失败

检查主机到 Milvus 的网络是否可达、端点协议与端口、数据库名、token 权限。本地 Milvus 通常通过 HTTP 暴露在 19530 端口。

嵌入服务商测试失败

检查 API key 是否已配置，以及是否允许使用所选模型。同时检查服务商的速率限制，以及 DSH Web 主机的出站网络访问。

稠密检索报维度不匹配

描述集合，对比绑定字段的维度与写入时使用的模型。修正绑定，或用预期模型重新写入；不要仅仅因为另一个模型能产出相同维度就换用它。

BM25 或混合检索被阻断

描述集合，查看它的检索能力部分。常见阻断原因有 bm25_route_absent、bm25_route_ambiguous、sparse_encoder_binding_absent、retrieval_plan_stale、retrieval_binding_absent。修复或重新保存集合策略、Function/index 或稠密绑定；混合检索不会降级为单一路由。

更新或移除

更新包，重启 DSH Web，刷新浏览器：

dsh plugin --profile web update @zilliz/dsh-milvus
dsh web

从 Web 配置档中移除：

dsh plugin --profile web remove @zilliz/dsh-milvus

移除插件不会改动或删除 Milvus 数据。如果不再需要已存储的 DSH 设置和凭据记录，请单独检查。

开发

安装依赖并运行本地检查：

npm ci
npm test
npm pack --dry-run

从本仓库把源码检出加载到 DSH Web，然后重启 DSH Web：

dsh plugin --profile web add "$PWD"

只读集成探测仅在提供端点时运行：

MILVUS_TEST_ENDPOINT=http://127.0.0.1:19530 npm run test:integration
MILVUS_TEST_ENDPOINT=http://127.0.0.1:19530 npm run test:integration:connection

服务商 API 冒烟测试单独受网络开关控制。在环境中设置任一受支持的 key，然后显式开启；没有 key 的服务商会跳过，key 和返回的向量都不会打印：

EMBEDDING_TEST_ALLOW_NETWORK=1 npm run test:integration:embeddings

变更集成测试会创建、搜索并删除一个一次性测试夹具。仅在非生产部署上、显式开启后运行：

MILVUS_TEST_ENDPOINT=http://127.0.0.1:19530 \
MILVUS_TEST_ALLOW_MUTATION=1 \
npm run test:integration:mutation

要验证从服务商到 Milvus 的完整链路，还需提供 Gemini API key。
这个测试会嵌入一条查询，通过 milvus_search 搜索一个一次性的 128 维集合，然后删除测试夹具：

MILVUS_TEST_ENDPOINT=http://127.0.0.1:19530 \
MILVUS_TEST_ALLOW_MUTATION=1 \
GEMINI_API_KEY=... \
npm run test:integration:retrieval

要验证 BM25 和两种混合重排模式，请使用非生产部署。测试默认先搜索已有的 mfs_scale_2000 BM25 集合，然后创建一个一次性混合集合，用完再删除。需要时可用 MILVUS_TEST_BM25_COLLECTION 覆盖已有集合名：

MILVUS_TEST_ENDPOINT=http://127.0.0.1:19530 \
MILVUS_TEST_ALLOW_MUTATION=1 \
npm run test:integration:hybrid

维护者发布

发布使用 npm Trusted Publishing。在拉取请求中更新 package.json 和 package-lock.json 里的版本号，跑完上面的本地检查，再把拉取请求合并进 master。随后 Publish npm package GitHub Actions 工作流会重跑测试，并通过 OIDC 发布新的公开包。它不使用 npm token，也不向维护者索要 OTP。

如果该版本已存在，工作流会在发布前失败。手动触发用于基础设施故障后重试一个尚未发布的新版本；它无法重新发布已有版本。正常发布流程中不要在本地运行 npm publish。

许可证

Apache-2.0。见 LICENSE。