mcpField
A
alicloud-ai-search-dashvector

alicloud-ai-search-dashvector

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

关于 alicloud-ai-search-dashvector

用于通过 DashVector Python SDK 管理集合和执行向量搜索的技能，涵盖文档写入与相似度查询，并支持过滤条件和稀疏向量。

主要功能

  1. 01按度量方式和字段结构创建集合
  2. 02写入稠密或稀疏向量文档
  3. 03按向量或文档 ID 查询
  4. 04应用过滤条件并选择输出字段

适用场景

  1. 01创建向量搜索集合
  2. 02幂等地写入文档
  3. 03通过范围过滤检索相似文档

安装

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

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

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

包含的文件

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

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

详细介绍

Category: provider

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（可选，字段类型字典）
写入文档
  • 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/alicloud-ai-search-dashvector/scripts/quickstart.py

环境变量：

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

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

Claude Code/Codex 注意事项

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

错误处理

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

验证

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

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

输出与证据

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

工作流

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

参考资料

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

  • 来源列表：references/sources.md

评论

支持 Markdown