轻量向量库检索搭建·文档向量化语义搜索元数据过滤知识库零显卡

轻量向量库 · 语义检索最短路径

## ⚠️ 先申请你自己的 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 Keyapi.a7w.cn一个 Key 调用全部 AI 算力;注册、充值、创建 Key 都在这
AI 插件市场aigc.a7w.cn浏览全部 AI 插件与接口说明
三剪客 · 一句话批量出片ks.a7w.cn短剧二创 / 影视解说 / 矩阵号批量混剪桌面客户端
视频超清 · 在线批量超分vr.a7w.cn网页版视频超分,批量处理,最高 4K
0人公司 · AI Agent 平台a7w.cn主站,了解整套 AI Agent 生态

同类文章