轻量向量库检索搭建·文档向量化语义搜索元数据过滤知识库零显卡
轻量向量库 · 语义检索最短路径
## ⚠️ 先申请你自己的 API Key
本 Skill 不内嵌任何密钥,也不代付费用。 请到
算力集市 api.a7w.cn 注册并创建你自己的 API Key
(新用户有赠送点数,可以先免费试跑几条)。
拿到后填进环境变量A7W_API_KEY,或直接传给--key参数。
请勿使用他人提供的 Key —— 用量与费用都记在 Key 所属账号上。
你想给一批文本做「按意思搜」—— 用户问「怎么退款」,能命中写着「申请售后」的那段话。
这件事的核心是一个向量库,而最短路径是:向量库留在本地,向量化交给 a7w。
向量化(embedding)和生成都走 算力集市 api.a7w.cn 的 OpenAI 兼容网关。
一个 base_url、一把 Key,本地不跑 embedding 模型、不下载权重、不占显卡。
| 你最关心 | 答案 |
|---|---|
| 多少钱 | 1 元 = 100 点。本地存、本地算相似度、本地过滤完全免费;只有向量化与生成扣点,按 tokens 计 |
| 要多久 | 向量化是同步返回,几百条文本几秒钟;检索在本地内存里做,微秒级 |
| 要装什么 | 什么都不用装。包里自带零依赖客户端,references/ 里还有一份纯 Python 的本地向量库实现 |
| 要不要显卡 | 不要。embedding 在 a7w,本地零 GPU |
| 数据在哪 | 在你自己机器上。向量与元数据落在你的文件里,离线也能检索 |
| 能商用吗 | 可以。生成内容的使用与合规责任由使用者承担 |
一、四种形态,按需要选
向量库可以只活在一个进程里,也可以起成服务给多台机器共用。先按数据量与并发选形态:
| 形态 | 数据在哪 | 适合 | 要额外起服务吗 |
|---|---|---|---|
| 进程内 | 内存 | 边写边试、跑通链路、做 demo | 不用 |
| 文件持久化 | 你指定的目录 | 笔记本上长期用的本地知识库 | 不用 |
| 自托管服务端 | 服务端 | 多个进程 / 多台机器共享一份数据 | 要 |
| 托管云 | 云端 | 不想自己运维 | 不用,但要凭据 |
⚠️ 最容易漏的一步:默认的进程内模式进程退出数据就没了。要留存就必须显式切到
「文件持久化」或「服务端」形态 —— 这是从原型走向「能留下东西」的第一处改动。
什么时候该换更大的库:上亿级向量、高并发在线检索、需要细粒度权限与多租户隔离时,
进程内/文件形态就不合适了,直接上专门的分布式向量库。
二、三分钟跑通
第一步:拿到你自己的 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 模型,记下它的输出维度。这个模型一旦用于建索引就不能再换 ——
换了要重新向量化全部文本。模型名不要猜。
第三步:向量化 —— 一个 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": ["退款需在收货后 7 天内发起", "生鲜类不支持无理由退款"]
}'
返回 data[].embedding 就是向量。这就是全部魔法 —— 后面的存取与相似度计算都在本地。
第四步:写入 + 检索 + 元数据过滤(本地,免费)
本 Skill 把「向量库存取」抽象成三个动作,任何向量库客户端都是这三步:
# 零依赖本地向量库:一个 JSON 文件 + 余弦相似度(完整实现见 references/本地向量库.md)
store.add(
ids=["doc1", "doc2"],
documents=["退款需在收货后 7 天内发起", "生鲜类不支持无理由退款"],
metadatas=[{"source": "help-center"}, {"source": "policy"}],
)
hits = store.query(
"怎么退款", # 查询文本,客户端会先向量化再算相似度
n=3, # 取前几条
where={"source": "help-center"}, # 元数据过滤
)
元数据过滤是刚需:只搜某个来源、某个时间之后、某个标签下的文档,
这一步在本地做,不花钱。
三、包里有什么
sanjianke-vector-store/
├── SKILL.md 本文件
├── README.md
├── LICENSE.md
├── references/
│ ├── 本地向量库.md 纯 Python 的向量库实现、相似度与过滤、离线做法
│ ├── 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 '{"...":"..."}'
references/本地向量库.md 给了一份只用 Python 标准库的向量库实现:
JSON 落盘、余弦相似度、元数据过滤、按 id 覆盖写入,复制就能跑。
四、素材要求
| 要求 | 说明 |
|---|---|
| 入库内容 | 先转成纯文本。PDF / Word 的解析是上游工序,不属于向量库的职责 |
| 单条长度 | 300~500 字一条,重叠 10%~15%;一条太短语义不足,太长会稀释相似度 |
| 元数据 | 只放简单标量(字符串 / 数字 / 布尔)。嵌套字典与列表先拍平成多个字段 |
| 命名 | id 用稳定的业务键(如 文件名#序号),别用会变的随机串,否则无法覆盖更新 |
| 维度 | 建索引前固定 embedding 模型与维度;换模型必须重建并重新灌数据 |
| 离线环境 | 要么先联网把向量算好落盘,要么改用不依赖模型的关键词检索(references/ 里有 BM25 实现) |
五、常见坑
| 坑 | 表现 | 怎么避 |
|---|---|---|
| 默认进程内模式 | 关掉脚本再跑,之前写的数据全没了 | 要留存就显式切到文件持久化或服务端形态,别停在内存模式 |
用 add 重复写同一个 id 以为会覆盖 | 集合里出现重复数据、污染检索结果 | 覆盖语义用 upsert;只改元数据用 update;add 就是纯新增 |
| 元数据过滤报错 | 过滤条件不生效或直接报错 | 元数据值只放简单标量;多层条件用 $and / $or 显式组合 |
n_results 比库里实际条数还大 | 报错或结果异常 | 先取实际条数,再取 min(n_results, count);本包示例代码已内置这个保护 |
| embedding 模型名靠猜 | 报错或返回异常 | 先用 GET /api/v1/models 查一次,以接口返回为准 |
| 换了 embedding 模型 | 旧向量与新向量不可比,结果全乱 | 索引与查询必须同一个模型;换模型要重建全部向量 |
| 离线机器上跑不通 | 首次调用失败 | 先在联网机器把向量算好落盘;或改用纯本地关键词检索 |
| 多实例各写各自的本地目录 | 数据「各写各的」,互相看不见 | 多进程 / 多机共享统一走服务端形态,让服务端成为唯一写入方 |
| 把 Key 写进代码 | 泄露即等于泄露余额 | 只从环境变量 A7W_API_KEY 或 ~/.a7w/config.json 读 |
| 一次塞几十条进上下文 | 又贵又跑题 | 先取 3~5 条;召回不准先改分块粒度,别急着加条数 |
六、计费
1 元 = 100 点,1 点 = ¥0.01,按量计费、没有月费。
| 动作 | 点数 | 折合 |
|---|---|---|
| 本地存取、算相似度、元数据过滤、BM25 关键词检索 | 0 | 免费,不经过平台 |
file_qa 文件问答 / 剧本解析 | 0 | 免费(实测口径) |
向量化 embeddings | 按 tokens 计点 | 一条文本一次,只在写入与查询时发生 |
生成答案 chat/completions | 按 tokens 计点 | 每次问答一小笔,max_tokens 可控 |
省点数的三条:① 分块别切太碎(块越多、向量化次数越多);② 已经算过的向量落盘复用,
不要每次重算;③ 纯关键词能解决的检索就用本地 BM25,完全不花点数。
平台同时给出标准价与租户价字段(
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 申请
- 不替代文档解析:PDF / Word 转文本要先自己处理好
- 不自带问答:向量库只负责「找到相关片段」,生成回答要靠大模型
- 不替代合规审查:入库内容与生成内容的合规责任由使用者承担
关于这个 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 生态 |