分布式向量数据库检索·亿级向量相似度搜索元数据过滤混合检索
分布式向量数据库 · 规模化相似度检索
## ⚠️ 先申请你自己的 API Key
本 Skill 不内嵌任何密钥,也不代付费用。 请到
算力集市 api.a7w.cn 注册并创建你自己的 API Key
(新用户有赠送点数,可以先免费试跑几条)。
拿到后填进环境变量A7W_API_KEY,或直接传给--key参数。
请勿使用他人提供的 Key —— 用量与费用都记在 Key 所属账号上。
向量数据库干的是一件很具体的事:把文本、图片、多模态数据算成的向量存起来,
并且能在几毫秒内找出「和这句话最像的 N 条」。
它的价值在于同一套接口覆盖三种规模:本机一个文件就能试、一台机器起容器能干正经活、
向量到几十亿条再换成集群。向量与标量字段一起存,所以检索可以叠加过滤条件
(按用户、按时间、按标签),也能做稠密向量 + 全文检索的混合检索。
模型这一层不用你操心:embedding 与生成都走
算力集市 api.a7w.cn 的 OpenAI 兼容网关 ——
一个 base_url、一把 Key、75 个在架模型,本地零显卡。
| 你最关心 | 答案 |
|---|---|
| 多少钱 | 1 元 = 100 点。库本身的存储与检索不经过 a7w、不花点数;只有 embedding 与生成扣点,按 tokens 计 |
| 要多久 | 检索毫秒级;写入取决于批大小;embedding 是同步返回 |
| 要装什么 | 什么都不用装即可先跑通 embedding 与问答(包里自带零依赖客户端);数据库本体按你要的规模自行选型 |
| 要不要显卡 | 不要。向量怎么算由 a7w 决定,本地零 GPU |
| 能上多大 | 本机文件 → 单机容器 → 集群,从小批量到几十亿条都有对应形态 |
| 能商用吗 | 可以。生成内容的使用与合规责任由使用者承担 |
一、三种规模,一套接口
| 规模 | 形态 | 适合 | 切换成本 |
|---|---|---|---|
| 本机文件 | 嵌入式,一个文件 | 快速开始、本地开发、跑通链路 | — |
| 单机服务 | 容器,带健康检查端点 | 正式业务的起步形态,多进程共享 | 只改连接串 |
| 集群 | 多节点 | 几十亿条向量、多租户、副本容错 | 只改连接串 |
好消息:建集合、写入、检索、过滤这些调用三种形态写法一致。
所以把连接方式抽成配置项,迁移时就只改一个 URI。
二、三分钟跑通
第一步:拿到你自己的 Key
到 api.a7w.cn 注册,创建 API Key(形如 sk-...):
export A7W_API_KEY=sk-你的key # Windows: $env:A7W_API_KEY="sk-你的key"
第二步:先定 embedding 模型与维度(这是全流程的第一块多米诺)
curl -sS "https://api.a7w.cn/api/v1/models" \
-H "Authorization: Bearer $A7W_API_KEY"
从返回里挑 embedding 模型,记下输出维度。这个维度就是建集合时要写的 dimension,
而集合的维度创建后无法修改。
第三步:向量化 —— 一个 base_url,一把 Key
curl -sS -X POST "https://api.a7w.cn/api/v1/embeddings" \
-H "Authorization: Bearer $A7W_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "<上一步挑的 embedding 模型名>",
"input": ["Who is Alan Turing?", "What is AI?"]
}'
把返回的 data[].embedding 写进你的向量库即可。**客户端里配置 embedding 时,base_url 就填 https://api.a7w.cn/api/v1,Key 用同一把** —— 后面换模型只改一个字符串。
第四步:检索(写入 → 检索 → 返回字段)
# 客户端写法(任意向量数据库客户端都是这四步)
client = Client(uri=URI, token=TOKEN) # 1. 连接(URI / token 从环境变量读)
client.create_collection( # 2. 建集合:维度必须与 embedding 模型一致
collection_name="demo_collection",
dimension=768, # ← 就是上一步的维度
)
client.insert(collection_name="demo_collection", data=rows) # 3. 写入(向量 + 标量字段)
hits = client.search( # 4. 检索
collection_name="demo_collection",
data=query_vectors, # 查询向量,支持批量
limit=2, # topK
output_fields=["text", "subject"], # 指定返回字段,别把向量本身也拉回来
filter='subject == "history"', # 元数据过滤(按客户端语法写)
)
第五步:答案生成也走同一个网关
检索到片段后,拼进上下文让大模型回答:
curl -sS -X POST "https://api.a7w.cn/api/v1/chat/completions" \
-H "Authorization: Bearer $A7W_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "DeepSeek-V4-Flash",
"messages": [
{"role": "system", "content": "只根据资料回答;资料里没有就说不知道。"},
{"role": "user", "content": "资料:\n1) ……\n问题:……"}
],
"temperature": 0.2,
"max_tokens": 800
}'
想完全不自建:平台的
file_qa应用可以直接对公网文档提问,接口免费,
用它给自建库做效果基线最省事。
三、包里有什么
sanjianke-vector-db/
├── SKILL.md 本文件
├── README.md
├── LICENSE.md
├── references/
│ ├── 规模化运维要点.md 索引选型、混合检索、多租户、加载与健康检查、备份监控
│ ├── api-openai-compat.md 网关接入:base_url、鉴权、模型发现、embedding 与 chat
│ ├── getting-started.md 注册、领 Key、配置与自检
│ └── 通用说明.md 权限、异步机制、错误码、计费口径
└── scripts/
└── a7w.py 零依赖客户端(库 + 命令行,只用 Python 标准库)
零安装用法
export A7W_API_KEY=sk-你的key
# 看平台上有哪些应用与接口
python3 scripts/a7w.py apps
# 免自建的文档问答(免费):先拿它确认「答得上来」,再决定自建规模
python3 scripts/a7w.py schema file_qa
python3 scripts/a7w.py call file_qa chat --json '{"...":"..."}'
四、素材与规格要求
| 要求 | 说明 |
|---|---|
| 向量维度 | 建集合前先固定 embedding 模型与维度;维度创建后改不了,换模型必须重建集合、重新灌数据 |
| 单条长度 | 300~500 字一条,重叠 10%~15% |
| 标量字段 | 你要用来过滤的字段(用户、时间、标签、来源)都要在建集合时一并规划,别等到上线才加 |
| 原始文件 | 向量库存的是向量与必要元数据;原文、图片文件本身放对象存储,这里只存引用 |
| 批量写入 | 分批 insert,批大小按你机器的内存调;一次灌几百万条要预留时间 |
| 连接信息 | URI 与 token 从配置或环境变量读,不要硬编码进代码 |
五、常见坑
| 坑 | 表现 | 怎么避 |
|---|---|---|
| dimension 不匹配 | 插入或检索时报维度错误 | 建集合前先确认 embedding 模型的输出维度;换模型必须重建集合,已有集合的维度改不了 |
| 集合未加载 | 检索报错说集合没有加载 | 先执行加载操作,再做 search;重启后要重新加载 |
| 把本机文件形态当生产库 | 功能与承载能力都撞墙 | 本机文件形态只用于跑通与开发;上线换单机服务或集群,连接方式抽成配置项 |
| 集群 / 单机重启后查询变慢 | 部分检索失败或延迟升高 | 重启后显式加载集合并等待完成;生产用副本与健康检查兜住 |
| 客户端与服务端版本差太多 | 找不到方法、字段名不对 | 客户端与服务端成对升级,不要跨大版本混用 |
| 服务装起来了但状态是 starting | 以为能用了 | 打健康检查端点确认 healthy,不是看容器 running |
| embedding 模型名靠猜 | 报错或结果异常 | 先用 GET /api/v1/models 查一次,以接口返回为准 |
output_fields 把向量也拉回来 | 返回体巨大、拖慢链路 | 只取你要用的标量字段与文本 |
| 过滤字段没建索引 | 带过滤的检索明显变慢 | 常用过滤字段单独建标量索引 |
| 混合检索没配好 | 只有语义结果、没有关键词结果 | 稠密与稀疏两路都要建索引与权重;先确认两路单独都能召回,再合并 |
| 把 Key 写进代码 | 泄露即等于泄露余额 | 只从环境变量 A7W_API_KEY 或 ~/.a7w/config.json 读 |
六、计费
1 元 = 100 点,1 点 = ¥0.01,按量计费、没有月费。
| 动作 | 点数 | 折合 |
|---|---|---|
| 向量库自身的存储、索引、检索、过滤 | 0 | 不经过 a7w,不花点数 |
file_qa 文件问答 / 剧本解析 | 0 | 免费(实测口径) |
向量化 embeddings | 按 tokens 计点 | 写入与查询时各发生一次 |
生成答案 chat/completions | 按 tokens 计点 | 每次问答一小笔,max_tokens 可控 |
省点数的三条:① 向量算一次就落库,查询时只向量化「问题」那一小段;
② 分块别切太碎;③ 能靠标量过滤缩小范围的,先过滤再检索。
平台同时给出标准价与租户价字段(
tenant_*,平台侧报价)两套字段,两者都未必等于实际结算价;
做预算一律以返回里的data.usage.points_cost为准,每次返回里的usage就是本次真实用量。
七、权限与边界
| 能力 | 是否申请 | 用途 |
|---|---|---|
| 网络访问 | 申请 | 调用 api.a7w.cn 的网关与接口(本 Skill 唯一的联网行为) |
| 读取文件 | 仅读取你指定的输入文件 | 用作待入库语料与连接配置 |
| 写入文件 | 仅在传入 --out 时 | 保存返回的 JSON |
| 凭证 | 读取你自己提供的 API Key | 从环境变量或 ~/.a7w/config.json 读取 |
| 子进程 / 后台常驻 | 视情况 | 单机服务与集群形态需要常驻进程 |
不内嵌任何密钥。 请求只发往 api.a7w.cn,不发送到其他任何地址。
- 不提供 Key、不代付费用:Key 必须你自己在 api.a7w.cn 申请
- 不负责生成向量:向量由 embedding 模型决定,本 Skill 只教你怎么接
- 不替代对象存储:原文与文件本身放别处
- 不做集群运维兜底:数据卷、备份、监控、升级策略要按你的业务自行规划
关于这个 Skill
作者亲测实操后发布,下载后可直接使用,自用商用都可以。
所有 AI 能力都走 算力集市 api.a7w.cn —— 一把 API Key 打通
大模型、语音、图像、视频、数字人等全部算力,注册即送点数,按量计费、没有月费。
| 你可能想问 | 答案 |
|---|---|
| 要不要额外部署 | 不用。下载本包即可使用,不必去别处找源码 |
| 怎么开始 | 到 api.a7w.cn 注册领 Key → 填进 A7W_API_KEY → 一条命令跑起来 |
| 能不能商用 | 可以 |
| 遇到问题找谁 | 见文末「联系我们」,作者本人答疑 |
使用中碰到任何问题 —— 报错、效果不理想、想省钱、想批量 —— 都欢迎加微信聊。
加好友时说一下是从哪个 Skill 找过来的,直接给你配套的示例。
联系我们
- 技术微信:9872659 —— 加好友时说一下是从哪个 Skill 找过来的,直接给你配套的 API Key 与能跑的示例。
- 要算力 / 要 API Key:算力集市 · 注册领 API Key —— 一个 Key 调用全部 AI 算力,注册、充值、创建 Key 都在这里。
- 更多 AI 插件与接口:AI 插件市场。
相关链接
| 链接 | 地址 | 说明 |
|---|---|---|
| 算力集市 · 注册领 API Key | api.a7w.cn | 一个 Key 调用全部 AI 算力;注册、充值、创建 Key 都在这 |
| AI 插件市场 | aigc.a7w.cn | 浏览全部 AI 插件与接口说明 |
| 三剪客 · 一句话批量出片 | ks.a7w.cn | 短剧二创 / 影视解说 / 矩阵号批量混剪桌面客户端 |
| 视频超清 · 在线批量超分 | vr.a7w.cn | 网页版视频超分,批量处理,最高 4K |
| 0人公司 · AI Agent 平台 | a7w.cn | 主站,了解整套 AI Agent 生态 |