Zilliz Cloud 向量数据库手册

适用版本：全托管 Milvus（Serverless / Dedicated / BYOC / On-Demand），客户端直接用 pymilvus（核实于 2026-11） 许可与形态：商业托管服务（Milvus 自托管为 Apache 2.0）；全托管 Milvus 一句话定位：Milvus 原班团队做的全托管 Milvus，买的是运维责任转移，但接入协议仍是标准 pymilvus，迁移成本低于专有 SDK 约定：$ 普通用户、# root 或 sudo、<xxx> 为占位符；标 ⚠️ 的是高危操作。 更新时间：2026-11（版本与 API 变化快，执行前请以官方文档复核）

目录

1. 它是什么、什么时候选它
2. 版本、许可与官方入口
3. 安装与启动
4. 核心概念与数据模型
5. 快速上手：完整 CRUD 示例
6. 索引与检索进阶
7. 生产部署与运维
8. 高频故障与排障
9. 常见坑与避坑清单
10. 速查表
11. 参考与延伸

1. 它是什么、什么时候选它

1.1 定位与架构

Zilliz Cloud 是由 Milvus 原班团队做的全托管 Milvus（官方表述 "made by the creators of Milvus"），形态有 Serverless / Dedicated / BYOC / On-Demand，自带 AUTOINDEX 与 Cardinal 引擎优化。你没有 Milvus 的 etcd / MinIO / 消息队列容器、没有 K8s、没有索引重建脚本，只有一个集群端点和一个 API key。

避坑：别去找「Zilliz 专属 Python SDK」。官方明确直接用 pymilvus 连接，这是它与 Pinecone 最重要的差别，也是迁移成本的主要来源（见第 1.8 节）。

1.2 核心命题：托管服务买的是运维责任转移

1.3 适合 / 不适合

适合：已在用或熟悉 Milvus / pymilvus，想免运维上云；希望保留标准协议以便日后迁回自建或换云；RAG / 推荐 / 以图搜图快速上线；流量波动需要 Serverless 弹性；先用 Free 集群做验证。

不适合：数据不得出境或有强合规要求且无法用 BYOC 解决；需要自定义索引参数与内核级调优（AUTOINDEX 由厂商托管）；预算固定且对 vCUs 计量敏感；需要完全私有化离线部署；依赖「各集群对应的具体 Milvus 引擎版本号」做兼容验证（该信息未核实，见第 11 章）。

1.4 规模与链路位置

Free 集群 5GB 存储约合 100 万条 768 维向量（官方资料口径）。QPS / 延迟官方承诺值官方资料未给出，以控制台与实测为准；示例用 3~4 维，实际常见 768 / 1024 / 1536。在线链路：embedding → client.insert → load_collection → client.search(..., filter=...) → 重排 / 拼 prompt。文档管理、权限、审计仍在调用方。

1.5 计费维度与额度限制

1.6 网络与合规（数据出境）

端点为 *.vectordb.zillizcloud.com / *.api.zillizcloud.com 的云上地址，数据落点由所选 region 决定；跨境写入场景需自行评估《个人信息保护法》《数据安全法》相关出境义务（经验性表述，非法律结论，以法务与官方合规文档为准）。企业出口需放行对应 HTTPS 域名；BYOC / Dedicated 可缓解部分合规诉求，具体网络与区域能力官方资料未给出，以官方文档为准。

1.7 「没有可核对的服务端版本号」的运维含义

各集群对应的具体 Milvus 引擎版本号未核实，用户也无法像自建 Milvus 那样 SELECT version() 拿到服务端版本。运维上等价于「只有客户端 SDK 版本 + 服务端能力档 + API 契约」：

1.8 SDK 绑定与迁移成本

避坑：与 Pinecone 的专有 SDK 不同，Zilliz 的数据层迁移成本低、运维层迁移成本高（计费、配额、挂起、密钥都得重做）。别把「用 pymilvus」误读成「零迁移成本」。

2. 版本、许可与官方入口

2.1 版本状态表（版本线分属多处，不可混用）

版本差异：Milvus 主线（如 3.0 / 2.6）、PyMilvus SDK、Milvus Lite 与 Zilliz Cloud 服务端是不同版本线，不可互相套用版本号。官方资料未提供 Zilliz 各集群对应的引擎版本，请勿按某个 Milvus 版本号推断托管侧行为。

2.2 许可与商业边界

商业托管服务；上游 Milvus 自托管为 Apache 2.0（不代表 Zilliz Cloud 服务端开源）。分层：Free / Serverless / Dedicated / BYOC / On-Demand。企业特性与 SLA 条款以官方为准。

2.3 官方入口表

2.4 版本识别命令

无服务端版本命令，只能识别客户端与连通性：

$ python -m pip show pymilvus
$ python -c "import os; from pymilvus import MilvusClient; c = MilvusClient(uri=os.environ['ZILLIZ_URI'], token=os.environ['ZILLIZ_API_KEY']); print(c.list_collections())"

2.5 近两年重要变更与弃用提醒

官方资料未提供 Zilliz Cloud 的逐版本变更史与弃用清单；可执行的事实是：当前以 AUTOINDEX 为默认索引、Free 集群存在 7 天挂起与删除不可恢复策略、credentials 只显示一次。其余以官方 release notes 为准，本篇不臆造。

3. 安装与启动

3.1 前置条件

Python 环境 + pymilvus；一个 Zilliz Cloud 账号、集群端点与 API key；企业出口放行对应 HTTPS 域名。无本地容器、无本地端口监听。

3.2 方式一：pip 安装客户端（完整命令）

$ python3 -m pip install pymilvus
$ export ZILLIZ_URI="<https://{cluster-id}.serverless.{region}.vectordb.zillizcloud.com>"
$ export ZILLIZ_API_KEY="<YOUR_API_KEY>"
$ python -c "import os; from pymilvus import MilvusClient; print(MilvusClient(uri=os.environ['ZILLIZ_URI'], token=os.environ['ZILLIZ_API_KEY']).list_collections())"

避坑：pymilvus 的具体版本以官方 Quickstart 为准，别把 Milvus Lite / 服务端版本号硬套到客户端；URI / API key 走环境变量与密钥管理，禁止入库入仓。

3.3 方式二：云控制台创建集群 + 客户端连通

控制台侧在 Web UI 创建集群（Serverless / Dedicated / On-Demand 等，无本地命令），创建时立即保存只显示一次的 credentials，随后用 MilvusClient(uri=..., token=...) 连通。list_collections() 正常返回即连通成功。

3.4 三种端点形态（别混用）

3.5 方式三：Docker / Helm

不适用：全托管服务没有自托管镜像。需要 Docker Compose / Helm 说明应选自建 Milvus（见 Milvus 分册）。

3.6 目录与端口表 / 健康检查 / 生产最小配置

4. 核心概念与数据模型

4.1 术语对照表

4.2 数据模型层级与字段

Cluster → Collection（create_schema() → add_field(FLOAT_VECTOR, dim=768) → create_collection）→ 文档（向量字段 + 标量字段）。官方 Quickstart 的 dim=768 与 metric_type="COSINE" 是示例值；本篇代码用 4 维便于运行。

4.3 距离度量与方向

官方资料明确 Quickstart 用 metric_type="COSINE"，并说明默认 AUTOINDEX 只选 metric；未给出完整度量枚举与打分方向。经验上 COSINE 类相似度越大越相似、L2 类距离越小越相似，但取值与阈值以官方文档为准，不要照搬自建 Milvus 的数值。

4.4 索引类型与生命周期

索引：AUTOINDEX（默认，只选 metric），另有 Cardinal 引擎优化；其余索引类型与参数官方资料未给出，以官方文档为准。

官方 Quickstart 的生命周期（逐字步骤链）：create_schema() → add_field(FLOAT_VECTOR, dim=768) → create_collection → prepare_index_params().add_index(index_type="AUTOINDEX", metric_type="COSINE") → create_index → load_collection → search(...)。

避坑：load_collection 是显式步骤。旧教程里「建完 collection 直接查」在需要 load 的链路里会查不到数据。一致性模型官方资料未明确，以官方文档为准。

5. 快速上手：完整 CRUD 示例

说明：用标准 pymilvus 连接 Zilliz Cloud。示例用 4 维向量便于直接运行；官方 Quickstart 用 dim=768，实际常见 768 / 1024 / 1536。URI / API key 需预先设为环境变量。

5.1 完整可运行示例（Python）

import os
from pymilvus import MilvusClient

# 连接：直接用 pymilvus，不是专有 SDK
client = MilvusClient(uri=os.environ["ZILLIZ_URI"],
                      token=os.environ["ZILLIZ_API_KEY"])
print("现有集合 =", client.list_collections())
COLL = "zilliz_demo"

# C：创建集合（高层 API，示例 4 维）
if COLL not in client.list_collections():
    client.create_collection(collection_name=COLL, dimension=4)

# U/C：插入文档
data = [
    {"id": 0, "vector": [0.1, 0.2, 0.3, 0.4], "text": "三国演义", "subject": "history"},
    {"id": 1, "vector": [0.9, 0.1, 0.2, 0.1], "text": "三体",     "subject": "scifi"},
]
client.insert(collection_name=COLL, data=data)
q = [[0.1, 0.2, 0.3, 0.45]]

# R：相似度检索
print("检索 =", client.search(collection_name=COLL, data=q, limit=3,
                             output_fields=["text"]))

# 带标量过滤检索
print("过滤 =", client.search(collection_name=COLL, data=q,
                             filter="subject == 'history'", limit=3,
                             output_fields=["text"]))

# U：更新（upsert 语义，同主键覆盖）
client.upsert(collection_name=COLL, data=[
    {"id": 0, "vector": [0.1, 0.2, 0.3, 0.4], "text": "三国演义（修订）", "subject": "history"}])

# D：删除
client.delete(collection_name=COLL, ids=[1])

# 清理
client.drop_collection(collection_name=COLL)
print("已清理", COLL)

避坑：upsert / delete / drop_collection 三个方法名按 pymilvus MilvusClient 通用形态给出，未查到官方明确说明，执行前以 pymilvus / Zilliz 官方文档为准（见第 11 章）。显式 AUTOINDEX 的写法是 index_params = client.prepare_index_params() 后 index_params.add_index(index_type="AUTOINDEX", metric_type="COSINE")，再按官方 Quickstart 调用 create_index / load_collection；这两步的逐字参数官方资料未给出，不臆造。

5.2 输出怎么读

list_collections() 返回集合名列表；search 返回命中集合，output_fields=["text"] 取回标量字段；filter="subject == 'history'" 是服务端标量过滤表达式。分数方向与阈值以官方文档为准（第 4.3 节）；id 是业务主键。

⚠️ 危险：drop_collection(collection_name=...) 是不可逆操作。Free 集群官方资料明确「删除后不可从回收站恢复」，执行前必须确认已导出源数据。

5.3 等价 REST / cURL 示例

官方资料未给出 REST 端点与请求体的逐字写法，为避免臆造 URL / 参数，以 https://docs.zilliz.com 的 API Reference 为准，本篇不编造 cURL 示例。

6. 索引与检索进阶

6.1 参数调优表

除官方资料明确的 dim=768 / metric_type="COSINE" / AUTOINDEX / filter 表达式外，默认值与推荐范围均为经验性表述，以官方文档与实测为准。

6.2 召回 / 延迟 / 成本取舍

索引结构由 AUTOINDEX + Cardinal 托管，用户侧可调的主要是 limit、filter、output_fields 与 schema。调大 limit 提升召回上限但抬升 vCUs 消耗；output_fields 取全字段会放大返回体。没有统一最优值，用自己的 query 集压测召回与 p99，并同步看 vCUs 账单。

6.3 标量过滤的 pre/post-filter 行为

pymilvus search(..., filter="subject == 'history'") 提供标量过滤表达式（官方资料第 1 节 Milvus Quickstart 逐字给出）。pre / post-filter 的具体行为、过滤后返回条数不足的处理官方资料未给出，以官方文档为准。

⚠️ 危险：过滤条件很 Selective 时返回条数可能少于 limit。若业务依赖「必须凑够 k 条」，要放大 limit 再截断，或按官方建议处理。

6.4 混合检索 / 多向量 / 稀疏 / 重排 / 量化

官方资料未提供 Zilliz Cloud 的 BM25 / 稀疏 / RRF / 量化压缩逐字能力说明，均以官方文档为准，本篇不臆造方法名与参数。可确定的是：混合检索的融合与重排逻辑仍在调用方，属于「托管不转移」的部分。

6.5 容量估算：不估内存，估配额与账单

托管侧不规划磁盘 / 内存，规划的是配额与 vCUs。单价官方资料未提供，以官方价格页为准；以上 GB / 条数换算为经验估算，以实测为准。

7. 生产部署与运维

7.1 前提：不自己搭集群

本章不写「部署 etcd / MinIO / MQ、配副本、调分片」—— 那些是 Zilliz Cloud 的责任。你要运维的是四件事：凭证（credentials / API key 的申请、保存、轮换）、成本（vCUs、存储、collection 数）、合规（区域与数据出境）、客户端生命周期（pin pymilvus、回归测试）。

7.2 备份与恢复

7.3 多可用区 / 高可用

高可用、多可用区、故障转移由托管架构与厂商负责；用户不配副本、不做跨区切换。需要更高等级时评估 Dedicated / BYOC，具体能力与区域清单以官方文档为准。健康检查用 client.list_collections() 与云控制台集群状态。

7.4 密钥轮换

⚠️ 危险：只显示一次的 credentials 一旦丢失没有第二次查看机会，只能重建凭证；一次性全量替换也会造成瞬时鉴权失败，必须灰度。

7.5 成本监控（含可用性风险）

7.6 升级与跨版本迁移

服务端无可升级项。你要做的是：pin pymilvus 版本 → 订阅 release notes → SDK 升级前在预发跑回归（重点覆盖 create_collection / insert / search(filter=...) / load_collection）→ 灰度发布。跨形态迁移（Free → Serverless → Dedicated）要改连接串（第 3.4 节）并重新核对配额。

版本差异：各集群对应的 Milvus 引擎版本号未核实，不要按某个 Milvus 版本的行为推断托管侧；能力差异按形态分档，不是按版本号分档。

7.7 安全基线 / 网络 / 日志

系统级服务管理（systemd / 防火墙基础）属通用运维，见根目录手册，本篇不重复。

8. 高频故障与排障

9. 常见坑与避坑清单

1. 现象：找「Zilliz 专属 SDK」浪费时间。原因：官方明确直接用 pymilvus。怎么做：from pymilvus import MilvusClient 配云端 uri / token 即可。
2. 现象：credentials 第二次登录看不到密码。原因：只显示一次。怎么做：创建时立即存入密钥管理服务，丢了只能重建凭证。
3. 现象：Free 集群放几天后连不上。原因：连续 7 天无操作自动挂起。怎么做：定时保活或升级到非 Free 形态，别把 Free 当生产常态。
4. 现象：删了 collection 想从回收站找回。原因：删除后不可从回收站恢复。怎么做：⚠️ 删除前先导出并二次确认，纳入删除审批。
5. 现象：第 6 个 collection 创建失败。原因：Free 上限 5 collections（Serverless 100）。怎么做：规划 collection 数量或升级形态。
6. 现象：schema 加到 65 个字段报错。原因：单 collection 最多 64 字段。怎么做：精简字段、合并标量列。
7. 现象：写入报容量相关错。原因：Free 5GB（约 100 万条 768 维向量）。怎么做：按 n × d × 4 估算，或升级形态。
8. 现象：建完 collection 直接 search 查不到。原因：Quickstart 链路里有显式 load_collection。怎么做：按 create_schema → add_field → create_collection → prepare_index_params/add_index(AUTOINDEX) → create_index → load_collection → search 顺序执行。
9. 现象：以为能手工调索引结构参数。原因：默认 AUTOINDEX 只选 metric，索引结构由托管侧选。怎么做：只指定 metric_type，结构调优诉求评估自建 Milvus。
10. 现象：把 Milvus 版本号写进 Zilliz 变更单。原因：各集群对应 Milvus 引擎版本号未核实、托管服务无公开版本号。怎么做：只 pin pymilvus 客户端版本，记录形态与 region（第 1.7 节）。
11. 现象：Dedicated / On-Demand 连接失败。原因：端点形态不同（:19530 / project endpoint）。怎么做：按第 3.4 节选对应端点，别混用。
12. 现象：vCUs 月底突然不够用。原因：Free 2.5M vCUs/月、注册赠 $100 credits / 30 天都有额度。怎么做：把 vCUs / 存储 / 到期日纳入告警（第 7.5 节）。
13. 现象：数据出境被合规卡住。原因：数据落点由 region 决定，跨境需评估出境义务。怎么做：选型阶段定 region，必要时评估 BYOC 或改国内云（见 国内云向量数据库.md）。
14. 现象：过滤后返回条数少于 limit。原因：过滤 Selective、过滤行为以官方为准。怎么做：放大 limit 再截断，别假设一定凑够 k 条。

⚠️ 危险：第 2、4 条会直接造成凭证或数据不可恢复；第 3 条是 Free 集群的固有可用性风险，生产不要依赖 Free 档。

10. 速查表

常用端口与路径小表

11. 参考与延伸

11.1 官方文档链接清单

11.2 与本册其他产品的关系

• 同属「托管服务买的是运维责任转移」：Pinecone.md（专有 SDK、迁移成本高）、国内云向量数据库.md（境内合规路线）。
• 上游协议：自建 Milvus / 阿里「向量检索服务 Milvus 版」/ 百度 Milvus 引擎都用 pymilvus，见 国内云向量数据库.md 与 Milvus 分册。
• 不想要托管、想自己控索引：见 03 分册 Faiss.md、hnswlib-Annoy-ScaNN.md。

11.3 进阶阅读方向

AUTOINDEX 与 Cardinal 引擎的行为边界；pymilvus 客户端版本与托管侧能力的对应关系；vCUs 计量建模与配额告警；Free 挂起 / 删除不可恢复下的备份与演练；从 Zilliz Cloud 迁回自建 Milvus 的改造清单。

11.4 本篇「未核实 / 以官方为准」事项