Alicloud Ai Search Milvus

类别：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 的注意事项

• insert 操作为异步执行；插入新数据后请等待数秒再执行搜索。
• 向量 dimension 必须与所用嵌入模型的输出维度保持一致。
• 使用 filter 参数实现租户隔离（tenant scoping）或数据集分区（dataset partitions）。

错误处理

• 认证错误：检查 MILVUS_TOKEN 是否正确，以及实例权限配置是否完备。
• 维度不匹配：确保所有待插入向量的维度与集合定义的 dimension 严格一致。
• 网络错误：确认 Milvus 实例的 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。

输出与证据

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

工作流

1) 明确用户意图、目标地域、资源标识符，并确认操作类型为只读（read-only）还是变更类（mutating）；
2) 首先执行一个最小化的只读查询（例如 list_collections() 或 get_collection_stats()），验证连接性与权限；
3) 使用显式参数和受控范围执行目标操作；
4) 核验结果正确性，并保存输出内容与证据文件。

参考资料

• PyMilvus MilvusClient 在阿里云 Milvus 上的使用示例
• 原始资料清单：references/sources.md