类别：provider

通过 PyMilvus 使用阿里云 Milvus（Serverless）

本技能使用标准的 PyMilvus API 连接阿里云 Milvus 并执行向量搜索。

前提条件

• 安装 SDK（建议在虚拟环境中安装，以避免 PEP 668 限制）：

python3 -m venv .venv
. .venv/bin/activate
python -m pip install --upgrade pymilvus

• 通过环境变量提供连接信息：
  • MILVUS_URI（例如：http://:19530）
  • MILVUS_TOKEN（格式为：:）
  • MILVUS_DB（默认值：default）

快速开始（Python）

import os
from pymilvus import MilvusClient

client = MilvusClient(
    uri=os.getenv("MILVUS_URI"),
    token=os.getenv("MILVUS_TOKEN"),
    db_name=os.getenv("MILVUS_DB", "default"),
)

# 1) 创建 collection
client.create_collection(
    collection_name="docs",
    dimension=768,
)

# 2) 插入数据
items = [
    {"id": 1, "vector": [0.01] * 768, "source": "kb", "chunk": 0},
    {"id": 2, "vector": [0.02] * 768, "source": "kb", "chunk": 1},
]
client.insert(collection_name="docs", data=items)

# 3) 搜索
query_vectors = [[0.01] * 768]
res = client.search(
    collection_name="docs",
    data=query_vectors,
    limit=5,
    filter='source == "kb" and chunk >= 0',
    output_fields=["source", "chunk"],
)
print(res)

脚本快速开始

python skills/ai/search/alicloud-ai-search-milvus/scripts/quickstart.py

所需环境变量：

• MILVUS_URI
• MILVUS_TOKEN
• MILVUS_DB（可选）
• MILVUS_COLLECTION（可选）
• MILVUS_DIMENSION（可选）

可选参数：--collection、--dimension、--limit、--filter。

Claude Code / Codex 使用注意事项

• 插入操作为异步执行；搜索新插入的数据前，请等待数秒。
• 确保向量的 dimension 与所用嵌入模型保持一致。
• 使用 filter 实现租户隔离或数据集分区。

错误处理

• 认证失败：检查 MILVUS_TOKEN 及实例权限配置。
• 维度不匹配：确保所有向量维度与 collection 定义的维度一致。
• 网络错误：确认实例的 VPC 或公网访问策略已正确配置。

验证

mkdir -p output/alicloud-ai-search-milvus
for f in skills/ai/search/alicloud-ai-search-milvus/scripts/*.py; do
  python3 -m py_compile "$f"
done
echo "py_compile_ok" > output/alicloud-ai-search-milvus/validate.txt

通过标准：命令退出码为 0，且成功生成文件 output/alicloud-ai-search-milvus/validate.txt。

输出与证据

• 将产物、命令输出及 API 响应摘要保存至 output/alicloud-ai-search-milvus/ 目录下。
• 证据文件中需包含关键参数（如地域、资源 ID、时间范围等），以保障可复现性。

工作流

1. 确认用户意图、地域、标识符，以及操作是否为只读或变更类操作。
2. 首先执行一个最小化的只读查询，用于验证连通性与权限。
3. 使用明确参数和限定作用域执行目标操作。
4. 校验结果，并保存输出与证据文件。

参考文档

• PyMilvus MilvusClient 在阿里云 Milvus 上的示例

• 源列表：references/sources.md