Category: provider
DashVector Vector Search
Use DashVector to manage collections and perform vector similarity search with optional filters and sparse vectors.
Prerequisites
- - Install SDK (recommended in a venv to avoid PEP 668 limits):
CODEBLOCK0
- - Provide credentials and endpoint via environment variables:
-
DASHVECTOR_API_KEY
-
DASHVECTOR_ENDPOINT (cluster endpoint)
Normalized operations
Create collection
- -
name (str) - INLINECODE3 (int)
- INLINECODE4 (str:
cosine | dotproduct | euclidean) - INLINECODE8 (optional dict of field types)
Upsert docs
- -
docs list of {id, vector, fields} or tuples - Supports
sparse_vector and multi-vector collections
Query docs
- -
vector or id (one required; if both empty, only filter is applied) - INLINECODE14 (int)
- INLINECODE15 (SQL-like where clause)
- INLINECODE16 (list of field names)
- INLINECODE17 (bool)
Quickstart (Python SDK)
CODEBLOCK1
Script quickstart
CODEBLOCK2
Environment variables:
- - INLINECODE18
- INLINECODE19
- INLINECODE20 (optional)
- INLINECODE21 (optional)
Optional args: --collection, --dimension, --topk, --filter.
Notes for Claude Code/Codex
- - Prefer
upsert for idempotent ingestion. - Keep
dimension aligned to your embedding model output size. - Use filters to enforce tenant or dataset scoping.
- If using sparse vectors, pass
sparse_vector={token_id: weight, ...} when upserting/querying.
Error handling
- - 401/403: invalid INLINECODE29
- 400: invalid collection schema or dimension mismatch
- 429/5xx: retry with exponential backoff
Validation
CODEBLOCK3
Pass criteria: command exits 0 and output/aliyun-dashvector-search/validate.txt is generated.
Output And Evidence
- - Save artifacts, command outputs, and API response summaries under
output/aliyun-dashvector-search/. - Include key parameters (region/resource id/time range) in evidence files for reproducibility.
Workflow
1) Confirm user intent, region, identifiers, and whether the operation is read-only or mutating.
2) Run one minimal read-only query first to verify connectivity and permissions.
3) Execute the target operation with explicit parameters and bounded scope.
4) Verify results and save output/evidence files.
References
- - DashVector Python SDK:
Client.create, Collection.upsert, INLINECODE34
- - Source list: INLINECODE35
技能名称：aliyun-dashvector-search
类别：provider
DashVector 向量搜索
使用 DashVector 管理集合，并通过可选的过滤器和稀疏向量执行向量相似性搜索。
前提条件
- - 安装 SDK（建议在虚拟环境中安装以避免 PEP 668 限制）：
bash
python3 -m venv .venv
. .venv/bin/activate
python -m pip install dashvector
- DASHVECTOR
APIKEY
- DASHVECTOR_ENDPOINT（集群端点）
标准化操作
创建集合
- - name（字符串）
- dimension（整数）
- metric（字符串：cosine | dotproduct | euclidean）
- fields_schema（可选，字段类型字典）
更新插入文档
- - docs：{id, vector, fields} 列表或元组
- 支持 sparse_vector 和多向量集合
查询文档
- - vector 或 id（必选其一；如果都为空，则仅应用过滤器）
- topk（整数）
- filter（类似 SQL 的 where 子句）
- outputfields（字段名称列表）
- includevector（布尔值）
快速入门（Python SDK）
python
import os
import dashvector
from dashvector import Doc
client = dashvector.Client(
apikey=os.getenv(DASHVECTORAPI_KEY),
endpoint=os.getenv(DASHVECTOR_ENDPOINT),
)
1) 创建集合
ret = client.create(
name=docs,
dimension=768,
metric=cosine,
fields_schema={title: str, source: str, chunk: int},
)
assert ret
2) 更新插入文档
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) 查询
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)
脚本快速入门
bash
python skills/ai/search/aliyun-dashvector-search/scripts/quickstart.py
环境变量：
- - DASHVECTORAPIKEY
- DASHVECTORENDPOINT
- DASHVECTORCOLLECTION（可选）
- DASHVECTOR_DIMENSION（可选）
可选参数：--collection、--dimension、--topk、--filter。
Claude Code/Codex 注意事项
- - 优先使用 upsert 进行幂等数据导入。
- 保持 dimension 与嵌入模型输出大小一致。
- 使用过滤器来限定租户或数据集范围。
- 如果使用稀疏向量，在更新插入/查询时传递 sparsevector={tokenid: weight, ...}。
错误处理
- - 401/403：DASHVECTORAPIKEY 无效
- 400：集合模式无效或维度不匹配
- 429/5xx：使用指数退避重试
验证
bash
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 pycompileok > 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
