mcpField
A
aliyun-dashvector-search

aliyun-dashvector-search

github.com/cinience数据与数据库39655 次安装11 周前更新
代码仓库

关于 aliyun-dashvector-search

使用 Alibaba Cloud DashVector 管理向量集合并执行相似度搜索的技能。通过 Python SDK 支持过滤查询、稀疏向量和多向量集合。

主要功能

  1. 01按模式创建集合
  2. 02写入文档和向量
  3. 03按向量或文档 ID 搜索
  4. 04应用过滤条件并选择输出字段
  5. 05支持稀疏向量和多向量

适用场景

  1. 01向集合写入向量
  2. 02通过过滤条件查找相似文档
  3. 03检索指定字段或向量

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/cinience/alicloud-skills --skill aliyun-dashvector-search

安装后在 Claude Code 中输入/aliyun-dashvector-search确认已加载。

包含的文件

除 SKILL.md 外，安装时一起下载的参考资料和脚本。

agents/
openai.yaml
references/
sources.md
scripts/
quickstart.py

详细介绍

类别：提供方

DashVector 向量搜索

使用 DashVector 管理集合并执行向量相似度搜索，可选择使用筛选条件和稀疏向量。

前置条件

  • 安装 SDK（建议在 venv 中安装，以避免 PEP 668 限制）：
python3 -m venv .venv
. .venv/bin/activate
python -m pip install dashvector
  • 通过环境变量提供凭据和端点：
    • DASHVECTOR_API_KEY
    • DASHVECTOR_ENDPOINT（集群端点）

标准化操作

创建集合
  • name（str）
  • dimension（int）
  • metric（str：cosine | dotproduct | euclidean）
  • fields_schema（可选的字段类型字典）
Upsert 文档
  • docs 列表，元素为 {id, vector, fields} 或元组
  • 支持 sparse_vector 和多向量集合
查询文档
  • vector 或 id（必须提供其中一个；如果两者都为空，则仅应用筛选条件）
  • topk（int）
  • filter（类 SQL 的 where 子句）
  • output_fields（字段名称列表）
  • include_vector（bool）

快速入门（Python SDK）

import os
import dashvector
from dashvector import Doc

client = dashvector.Client(
    api_key=os.getenv("DASHVECTOR_API_KEY"),
    endpoint=os.getenv("DASHVECTOR_ENDPOINT"),
)

# 1) Create a collection
ret = client.create(
    name="docs",
    dimension=768,
    metric="cosine",
    fields_schema={"title": str, "source": str, "chunk": int},
)
assert ret

# 2) Upsert docs
collection = client.get(name="docs")
ret = collection.upsert(
    [
        Doc(id="1", vector=[0.01] * 768, fields={"title": "Intro", "source": "kb", "chunk": 0}),
        Doc(id="2", vector=[0.02] * 768, fields={"title": "FAQ", "source": "kb", "chunk": 1}),
    ]
)
assert ret

# 3) Query
ret = collection.query(
    vector=[0.01] * 768,
    topk=5,
    filter="source = 'kb' AND chunk >= 0",
    output_fields=["title", "source", "chunk"],
    include_vector=False,
)
for doc in ret:
    print(doc.id, doc.fields)

脚本快速入门

python skills/ai/search/aliyun-dashvector-search/scripts/quickstart.py

环境变量：

  • DASHVECTOR_API_KEY
  • DASHVECTOR_ENDPOINT
  • DASHVECTOR_COLLECTION（可选）
  • DASHVECTOR_DIMENSION（可选）

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

Claude Code/Codex 使用说明

  • 优先使用 upsert 进行幂等数据导入。
  • 确保 dimension 与嵌入模型的输出维度一致。
  • 使用筛选条件限定租户或数据集范围。
  • 如果使用稀疏向量，请在 upsert/查询时传入 sparse_vector={token_id: weight, ...}。

错误处理

  • 401/403：DASHVECTOR_API_KEY 无效
  • 400：集合架构无效或维度不匹配
  • 429/5xx：使用指数退避重试

验证

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

通过标准：命令以 0 退出，并生成 output/aliyun-dashvector-search/validate.txt。

输出与证据

  • 将产物、命令输出和 API 响应摘要保存到 output/aliyun-dashvector-search/ 下。
  • 在证据文件中包含关键参数（区域/资源 ID/时间范围），以便复现。

工作流

  1. 确认用户意图、区域、标识符，以及操作是只读还是会修改数据。
  2. 先运行一次最小化的只读查询，以验证连接和权限。
  3. 使用明确的参数和有限的范围执行目标操作。
  4. 验证结果并保存输出/证据文件。

参考资料

  • DashVector Python SDK：Client.create、Collection.upsert、Collection.query

  • 来源列表：references/sources.md

评论

支持 Markdown