alibabacloud-milvus-manage

Alibaba Cloud Milvus 全栈 Skill

前置条件

[必须] CLI User-Agent — 每次调用 aliyun CLI 命令都必须包含： --user-agent AlibabaCloud-Agent-Skills/alibabacloud-milvus-manage

[必须] PyMilvus User-Agent — 每次通过 pymilvus SDK 建立连接都必须包含： grpc_options={"grpc.primary_user_agent": "AlibabaCloud-Agent-Skills/alibabacloud-milvus-manage"}

Alibaba Cloud CLI 版本必须为 >= 3.3.3。

区分以下两个平面：

• 控制平面：使用 aliyun CLI 管理 Alibaba Cloud 托管的 Milvus 实例。
• 数据平面：使用 pymilvus Python 代码操作 Milvus。

将 SKILL.md 视为路由器。加载 references/*.md 以获取详细命令、参数和示例。

范围

在以下场景中使用此 Skill：

• Alibaba Cloud 托管 Milvus 实例生命周期：创建、检查、扩缩容、重命名、配置、网络、白名单。
• 使用 pymilvus 的 Milvus Python SDK 工作流：连接、集合、向量、搜索、索引、分区、数据库、RBAC。
• 基于 Milvus 的检索用例：语义搜索、混合搜索、全文搜索、RAG 模式。

以下场景不使用此 Skill：

• 在 Docker、Helm、Kubernetes 或 Milvus Operator 上部署自托管 Milvus，
• Milvus Java / Go / Node SDK，
• 其他 Alibaba Cloud 产品，例如 ECS、RDS、OSS、EMR、Kafka、StarRocks，
• 其他向量数据库，例如 Zilliz Cloud、Pinecone、Qdrant 或 Weaviate。

路由请求

控制平面

当用户询问以下内容时，路由到此处：

• 创建、扩缩容、重命名或检查 Milvus 实例，
• 连接地址、组件规格、配置、公网、白名单，
• Alibaba Cloud Milvus 的 VPC/VSwitch 前置条件，
• Milvus REST 风格的 CLI API、创建参数或控制平面故障排查。

阅读：

• 首次使用流程：references/getting-started.md
• 创建 / 列表 / 详情 / 扩缩容 / 释放：references/instance-lifecycle.md
• 配置 / 网络 / 检查 / 故障排查：references/operations.md
• 创建字段含义和模板：references/create-params.md
• 原始 API 字段参考：references/api-reference.md
• RAM 权限：references/ram-policies.md

数据平面

当用户询问以下内容时，路由到此处：

• 使用 Python 连接 Milvus，
• 创建集合或 Schema，
• 插入、更新插入、查询、删除或搜索向量，
• 混合搜索、BM25 全文搜索、迭代器、索引，
• 分区、数据库、用户、角色或权限，
• 基于 Milvus 的 RAG 或语义检索模式。

阅读：

• 集合 Schema 和生命周期：references/collection.md
• 向量 CRUD、搜索、混合搜索、全文搜索：references/vector.md
• 索引类型和度量：references/index.md
• 分区：references/partition.md
• 数据库：references/database.md
• RBAC：references/user-role.md
• 常见解决方案模式：references/patterns.md

通用防护措施

• 首先判断所属平面。不要混用控制平面实例操作和数据平面 SDK 代码。
• 执行破坏性操作前先确认。
• 将不可信用户输入传入 Shell 命令或代码前，先进行验证。
• 优先加载有针对性的参考文档，而不是在此文件中保留大量内联示例。

控制平面规则

必需的环境配置

• 重用已配置的 aliyun 配置文件。调用 API 前，确认凭证已配置。
• 每次调用 aliyun CLI 都必须包含所需的 User-Agent 标志：

aliyun ... --user-agent AlibabaCloud-Agent-Skills/alibabacloud-milvus-manage

• 通过 aliyun 调用 Milvus OpenAPI 时必须包含 --force。

前置条件

在创建或进行重大修改之前：

1. 与用户确认 RegionId。
2. 验证该区域中的 VPC 和 VSwitch 资源。
3. 创建时，记录 ZoneId、VpcId 和 VSwitchId。
4. 如果请求不明确，询问用户需要用于开发/测试的独立部署，还是生产级 HA 集群。

基线决策规则：

• standalone_pro 是开发/测试的默认选项。
• HA 集群用于生产环境。
• 在 HA 模式下，streaming、data、mix_coordinator 和 query 必须至少使用 4 CU；proxy 必须至少使用 2 CU。

详细模板和字段定义见 references/instance-lifecycle.md 和 references/create-params.md。

CLI 调用模式

使用 API 预期的参数模式。不要自行变通。

# get / delete: business params in URL query
aliyun milvus get "/path?RegionId=<region>&instanceId=<id>" --RegionId <region> --force --user-agent AlibabaCloud-Agent-Skills/alibabacloud-milvus-manage

# post / put with request body: business params in --body JSON
aliyun milvus post "/path?RegionId=<region>" --RegionId <region> --body '{...}' --force --user-agent AlibabaCloud-Agent-Skills/alibabacloud-milvus-manage

# post with query-style flags: business params as --Flag value
aliyun milvus post "/path" --RegionId <region> --InstanceId <id> --force --user-agent AlibabaCloud-Agent-Skills/alibabacloud-milvus-manage

规则：

• 始终传入 --RegionId <region>。
• 对于 CreateInstance 和 UpdateInstance，使用 --body。
• 对于详情、配置、网络、ACL 和重命名等查询类 POST API，使用 --Flag value。
• 除非已验证，否则不要将用户提供的原始文本直接放入 shell 命令。

运行时安全

• 在控制平面操作期间，不要下载并执行远程脚本或未经审查的依赖项。
• 不要对不可信输入使用 eval 或 source。
• 为 CLI 调用设置合理的超时。读取操作优先使用较短超时；对于长时间运行的异步操作，应限制轮询时间。
• 对于列表 API，不要盲目信任 total；检查返回的数组。
• 重试前先阅读完整错误消息。对于限流可以自动重试，但不适用于任意失败。

禁止的操作

• 严禁通过此 Skill 删除实例（DeleteInstance）。 如果用户要求删除/释放 Milvus 实例，不要通过 aliyun CLI 执行 Milvus 删除命令。应改为指导用户通过 Alibaba Cloud Milvus 控制台 删除实例。

破坏性操作

以下操作必须先获得明确确认：

• 修改实例配置，
• 禁用公网访问。

使用以下模板：

即将执行：<API>，目标：<InstanceId>，影响：<Description>。是否继续？

对于配置变更和网络故障排查流程，请先阅读 references/operations.md 或 references/instance-lifecycle.md。

输出风格

• 将实例列表概括为简洁的表格。
• 在相关情况下，突出显示 instanceId、instanceName、status、dbVersion、ha、paymentType 和连接端点。
• 将时间戳转换为易读时间。
• 在有帮助时，使用 --cli-query 或 jq 精简冗杂的负载。

数据平面规则

优先建立连接

编写任何 pymilvus 代码之前，请询问：

1. 部署类型：Milvus Lite、自托管独立部署/集群，或 Alibaba Cloud 托管实例，
2. URI 或端点，
3. 身份验证方法，以及必要时所需的凭据，
4. 如果不使用 default，则询问数据库名称。

不要假设连接参数。只有在用户明确需要本地嵌入式模式时才使用 Milvus Lite。

最简连接形式：

from pymilvus import MilvusClient

PYMILVUS_GRPC_OPTIONS = {
    "grpc.primary_user_agent": "AlibabaCloud-Agent-Skills/alibabacloud-milvus-manage"
}

client = MilvusClient(
    uri="<USER_URI>",
    token="<USER_TOKEN>",
    grpc_options=PYMILVUS_GRPC_OPTIONS,
)

• 每个 MilvusClient(...) 和 connections.connect(...) 示例都必须传入 grpc_options=PYMILVUS_GRPC_OPTIONS。
• 不要生成缺少 grpc_options=PYMILVUS_GRPC_OPTIONS 的 pymilvus SDK 连接代码。

对于异步用法、Schema 详情和特定部署模式的用法，请加载相关参考文档。

数据安全与正确性

• 绝不要生成虚假或占位向量。始终使用真实的嵌入模型。
• 查询嵌入模型必须与用于创建已存储向量的模型一致。
• 向量维度必须与集合 Schema 完全一致。
• 搜索或查询前必须先加载集合。
• 执行 drop_collection、drop_database 或大规模删除等破坏性操作前，必须先确认。
• 除非用户有明确的性能要求，否则优先使用 AUTOINDEX。

最简工作流

对于大多数 SDK 任务：

1. 加载 references/collection.md，了解架构和集合操作，
2. 加载 references/vector.md，了解插入／搜索／查询／删除模式，
3. 如果用户关注索引类型、度量指标或调优，则加载 references/index.md，
4. 仅在任务确实需要时，才添加分区／数据库／RBAC 参考资料。

常见模式

• 快速创建原型集合：references/collection.md
• 向量 CRUD 和相似度搜索：references/vector.md
• 混合搜索或全文搜索：references/vector.md
• RAG／语义检索模式：references/patterns.md
• 索引调优：references/index.md

建议的响应流程

如果是控制平面任务

1. 确认区域和目标实例范围。
2. 阅读对应的控制平面参考资料。
3. 使用正确的参数模式运行命令。
4. 报告关键字段、后续状态以及需要等待的条件。

如果是数据平面任务

1. 先询问连接详情。
2. 仅阅读完成所请求 SDK 任务所需的参考资料。
3. 编写或说明 pymilvus 代码，其中包含实际嵌入向量、实际连接占位符，以及 grpc_options=PYMILVUS_GRPC_OPTIONS。
4. 如有需要，指出架构、加载状态、索引和维度方面的注意事项。

参考资料索引

• references/getting-started.md：从头创建第一个 Milvus 实例
• references/instance-lifecycle.md：创建、检查、扩缩、重命名、释放
• references/operations.md：配置、网络、ACL、检查、故障排除
• references/create-params.md：创建请求体字段和组件模板
• references/api-reference.md：原始 API 签名和返回字段
• references/collection.md：架构和集合生命周期
• references/vector.md：插入、搜索、混合搜索、BM25、迭代器
• references/index.md：索引类型和度量指标指南
• references/partition.md：分区操作
• references/database.md：数据库操作
• references/user-role.md：用户、角色、权限
• references/patterns.md：RAG 和语义搜索模式
• references/ram-policies.md：IAM/RAM 策略