zilliztech/dsh-milvus

面向 DSH 的 Milvus

面向 DSH 的 Milvus 让 DSH Web 智能体可以在聊天中检查并搜索 Milvus 部署。
它支持本地 Milvus 和 Zilliz Cloud、精确实体查找、标量查询、BM25 全文搜索，
以及稠密+BM25 混合检索。
自然语言稠密搜索使用由 DSH 管理的嵌入提供方；BM25 完全基于集合的 Milvus
Function schema 运行。

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

要求

- DSH Web 0.1.0-rc.7 或更高版本
- Node.js 22.19 或更高版本
- 可从 DSH Web 主机访问的 Milvus HTTP(S) 端点
- 可选：来自受支持嵌入提供方之一的 API 密钥，用于稠密搜索和混合搜索

安装

将该包安装到 DSH Web 配置文件中：

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

如果 dsh 未全局安装：

npx --yes @deepseek-ai/dsh@0.1.0-rc.7 plugin --profile web add @zilliz/dsh-milvus
npx --yes @deepseek-ai/dsh@0.1.0-rc.7 web

安装或更新插件后，请重启 DSH Web 并刷新浏览器页面。

设置插件

打开 Settings → Plugins → Milvus for DSH。设置顺序与使用 Milvus 的顺序相同：
连接部署、选择集合，然后仅启用你需要的搜索能力。

连接 Milvus

选择 Local Milvus Standalone 或 Zilliz Cloud，然后输入端点和可选数据库。
本地 Milvus 通常使用 http://127.0.0.1:19530 和数据库 default。Zilliz Cloud
需要其 HTTPS 端点和令牌。对于需要身份验证的本地部署，请选择
Add optional authentication 并输入其令牌。

保存后，使用 Test connection。该卡片会将表单折叠为连接摘要，使部署详情
不再与集合设置相互干扰。

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

活动连接会在新聊天开始时绑定。更改它会影响新聊天；它不会悄悄地将现有聊天
切换到不同的部署。

选择集合

Collection 选择器会根据已连接的 Milvus 数据库填充。选择一个集合后，DSH 会在
主机上检查其字段、索引和 Functions。在正常设置路径中，你无需输入集合或 schema
字段名称。

随后该卡片会报告四项能力：

- Scalar query 在成功检查 schema 后即准备就绪。
- BM25 search 在集合具有一条有效的 Milvus BM25 Function 路由时即准备就绪。
它不需要外部 API 密钥。
- Semantic search 在其嵌入提供方和已发现的 FloatVector 字段完成映射后
即准备就绪。
- Hybrid search 在 BM25 和语义搜索都准备就绪时自动变为可用。

在需要时启用语义搜索
此步骤仅适用于自然语言稠密检索和混合检索。BM25
文本搜索不使用外部嵌入提供程序。

1. 在语义搜索功能上选择 启用。
2. 选择一个与集合中已存储向量相匹配的提供程序和模型。
3. 输入提供程序 API 密钥。
4. 从所选集合中发现的一个 FloatVector 字段中选择。
5. 选择 启用语义搜索。

如果已配置提供程序，请复用它，而不是再次输入密钥。该字段必须包含使用该确切模型和向量空间创建的文档向量。仅维度匹配本身并不能证明兼容性；例如，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 令牌和嵌入 API 密钥通过只写 DSH Credentials 保存。它们的值绝不会存储在插件设置中、保存后返回给浏览器，或添加到聊天历史记录中。

聊天工具接受自然语言查询文本；它从不要求用户或代理提供浮点数列表。DSH 在主机上生成查询向量，根据集合模式检查其维度，并将其直接发送到 Milvus。

仅在必要时使用高级设置
高级设置默认处于折叠状态。仅在需要移除向量映射、在多个经 schema 验证的 BM25 路由中进行选择，或更改混合排序时，才将其展开。

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

搜索的集合要求

插件在搜索每个集合之前会先检查它，并报告稠密检索、BM25 和混合检索是否就绪。

稠密搜索需要配置到某个带维度的 FloatVector 字段的绑定。BM25 搜索需要满足以下所有集合条件：

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

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

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

在聊天中使用

在激活所需的 Milvus 配置文件后，开始一个新聊天。一个有用的初始操作序列是：

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

agent 应先发现并描述集合，然后再使用其字段。当集合、字段、分区或过滤器存在歧义时，它应当询问而不是猜测。

可用工具

| 工具 | 用途 |
| --- | --- |
| milvus_list_collections | 列出聊天所绑定配置文件可见的集合。 |
| milvus_describe_collection | 显示 schema、索引、加载状态，以及稠密/BM25/混合检索的就绪状态或阻塞项。 |
| 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 密钥、原始提供商错误正文或生成的向量。

混合重排是 milvus_hybrid_search 的一部分，而不是单独的工具：

- 无重排参数：使用 k=60 的 RRF；
- 显式 RRF：用户可以提供一个其他正数 k；
- 显式 Weighted：用户必须同时提供 denseWeight 和 bm25Weight，每个值从 0 到 1，且不能同时为零。

命名权重可防止路由顺序错误。如果用户仅要求“Weighted”而未提供值，代理会要求提供两个权重，而不是进行猜测。搜索结果会说明生效的重排值，以及它们来自请求、集合策略还是插件默认值。

没有嵌入密钥时会发生什么

集合列表、描述、精确获取、标量查询以及 schema 兼容的 BM25 搜索继续正常工作。稠密和混合搜索被阻止，并给出特定的配置结果：

- 无集合绑定：retrieval_binding_absent；
- 绑定引用了缺失的提供商配置文件：embedding_profile_absent；
- API 密钥缺失或不可用：embedding_credential_unavailable。

插件不会回退到聊天模型、其他提供商、猜测的向量或标量查询。

隐私与安全

- 稠密搜索查询文本从 DSH 主机发送到绑定中选择的嵌入提供商。
- 生成的向量保留在主机内存中，仅发送到 Milvus。
- Milvus 令牌和提供商密钥保留在 DSH Credentials 边界之后。
- 输出字段必须存在于所检查的 schema 中，且必须是标量。
- 过滤器只能引用从该集合中发现的标量字段。
- 精确路由字段可防止已保存的 BM25 计划静默切换路由。已保存的 schema 指纹（如果存在）还会在任何检索 schema 变更后阻止该计划，直到其被审查。
- 插件不暴露任何变更、schema、索引、数据库、用户、角色或管理操作。
- 目前不支持外部稀疏编码器、模型/交叉编码器重排、数据摄取、自定义嵌入端点和手动向量输入。

故障排除

设置卡片缺失

确认该包已安装在 web 配置文件中，重启 DSH Web，并刷新页面：

dsh plugin --profile web why @zilliz/dsh-milvus
工具提示没有可用的 Milvus 配置文件

创建一个 Milvus 配置文件，将其设为新聊天的活动配置，然后开始一个新聊天。
现有聊天会保留其原始会话绑定。

Milvus 连接测试失败

检查主机到 Milvus 的网络可达性、端点协议和端口、数据库
名称以及令牌权限。本地 Milvus 通常通过端口 19530 暴露 HTTP。

嵌入提供程序测试失败

检查 API 密钥是否已配置并允许使用所选模型。
还要检查提供程序的速率限制以及 DSH Web
主机的出站网络访问。

稠密搜索报告维度不匹配

描述集合，并将绑定字段的维度与摄取期间使用的模型
进行比较。修正绑定或使用预期
模型重新摄取；不要仅仅因为另一个模型能产生相同
维度就选择它。

BM25 或混合搜索被阻止

描述集合并阅读其检索能力部分。常见的
阻止项有 bm25_route_absent、bm25_route_ambiguous、
sparse_encoder_binding_absent、retrieval_plan_stale 和
retrieval_binding_absent。修复或重新保存集合策略、
Function/索引或稠密绑定；混合搜索不会降级为单一
路由。

更新或移除

更新包，重启 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 冒烟测试单独受网络限制。在环境中设置任意受支持的密钥，
然后明确选择启用；没有密钥的提供程序会被
跳过，并且不会打印密钥或返回的向量：

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 密钥。
此测试会嵌入一个查询，通过 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 令牌，也不要求维护者提供 OTP。

如果该版本已存在，工作流会在发布前失败。其手动触发旨在基础设施故障后重试一个尚未发布的新版本；它无法重新发布现有版本。不要将本地运行 npm publish 作为正常发布路径的一部分。

许可证

Apache-2.0。参见 LICENSE。