LocalAI Stores 向量存储 API 实战指南set/get/delete/find 四个端点与 local-store、valkey-store 后端详解【免费下载链接】LocalAILocalAI is the open-source AI engine. Run any model - LLMs, vision, voice, image, video - on any hardware. No GPU required.项目地址: https://gitcode.com/GitHub_Trending/lo/LocalAILocalAI 的 Stores 功能为本地部署的 AI 服务提供了一个低级别的向量相似性查询能力无需引入外部向量数据库直接通过 HTTP API 完成 embedding 的写入、读取、删除与 Top-K 近邻检索。本文基于 docs/content/features/stores.md 完整讲解四个核心端点的请求/响应格式、两种内置后端local-store、valkey-store的选型与配置方法并结合仓库源码剖析 HTTP 端点到 gRPC 后端的完整调用链帮助你在 RAG 检索、路由缓存、人脸库等场景中直接使用这一能力。什么是 Stores一个只有四个动词的低层向量 APIStores 是 LocalAI 的实验性功能定位是帮助开发者用相似性搜索来查询数据的低层 API全部能力浓缩为四个操作get、set、delete、find。典型使用场景是你已经拥有了文本的 embedding一个用数值向量表示文本信息的数组它可能来自 BERT 等 AI 模型生成也可能来自词频等传统方法现在想找与该向量最相似的文本。做法是先把所有文本分块后逐一建立 embedding 写入 store再用查询文本的 embedding 调用find做相似性比较。在此之前这类需求通常要求直接对接外部向量数据库或向量库而 Stores 让你通过 LocalAI API 本身完成这一切。文档同时给出一个务实提醒对 embedding 做相似性搜索只是检索retrieval的一种方式更高层的 API 可能会综合考量更多因素因此对于完整 RAG 方案Stores 未必是最合适的起点——它更适合作为构建块被上层功能复用。事实上LocalAI 内部就有多处直接建立在此之上人脸识别1:N 人脸识别流程/v1/face/register、/v1/face/identify、/v1/face/forget就是构建在通用 store 之上的面向人脸的 API 详见 人脸识别文档路由与 KNN 分类器core/backend/stores.go 中的VectorStore接口定义了SearchTop-1与SearchKTop-K语义注释明确说明它服务于router 的 embedding 缓存与 KNN 分类器实现上最终委托给local-storegRPC 后端并按 store 名做命名空间隔离。数据模型列式columnar格式与键向量约束理解 Stores 的数据形态对正确构造请求至关重要文档给出了三条核心约定列式格式响应不是键值对象数组而是两个独立数组——一个keys键数组和一个values值数组keys[i]对应values[i]。这一约定在内部 gRPC 封装中同样被强调见 pkg/store/client.go 中SetCols/GetCols/DeleteCols的注释Its in columnar format so that keys[i] is associated with values[i]。键是浮点向量值是字符串keys是 32 位浮点数数组gRPC 层对应[][]float32HTTP JSON 层对应嵌套数组values是字符串gRPC 中为字节。请求/响应结构体定义在 core/schema/localai.go// 节选自 core/schema/localai.go type StoreCommon struct { Backend string json:backend,omitempty } type StoresSet struct { Store string Keys [][]float32 json:keys Values []string json:values StoreCommon } type StoresGetResponse struct { Keys [][]float32 json:keys Values []string json:values } type StoresFindResponse struct { Keys [][]float32 json:keys Values []string json:values Similarities []float32 json:similarities }键向量必须等长归一化更利于检索同一个 store 中所有键向量长度必须一致向量归一化单位化时对搜索性能最有利。写入时后端会自动检测向量是否归一化以及其长度长度不一致会直接报错。这一点在 core/backend/stores.go 的StoreBackend注释中也有印证不同 store 命名空间必须落到各自独立的后端进程否则 512 维的人脸特征与 192 维的声纹特征共享同一个进程时会触发 Try to add key with length N when existing length is M 之类的错误。所有端点都接受一个store字段用于指定操作的 storestore 是按需即时创建的on the fly无需预先初始化。路由注册与鉴权从 URL 到 gRPC 的调用链四个端点均为 POST 方法在 core/http/routes/localai.go 中统一注册POST /stores/set POST /stores/get POST /stores/delete POST /stores/find并且它们被纳入 LocalAI 的鉴权特性体系中core/http/auth/features.go 将这四个路由映射到FeatureStores特性开关即可以通过鉴权配置按特性粒度控制这些端点的访问。每个请求的处理流程在 core/http/endpoints/localai/stores.go 中实现模式高度一致绑定 JSON 请求体 → 调用backend.StoreBackend(...)解析出对应 store 的 gRPC 后端 → 委托 pkg/store/client.go 中的SetCols/GetCols/DeleteCols/Find完成实际操作。pkg/store/client正是文档所说的内部 gRPC API 的封装供 LocalAI 内部如人脸识别、路由缓存复用对外暴露的 HTTP JSON API 与 gRPC API 是一一对应的镜像。StoreBackendcore/backend/stores.go是理解后端选择逻辑的关键它以store字段即该 store 的 model ID去ModelConfigLoader中查找同名模型配置若存在则取用其backend与options——这就是下文 Valkey 后端per-store 模型配置的落点请求中显式传入的backend字段优先级更高会覆盖配置中的值两者都未指定时回退到local-store默认并保持零配置可用每次加载通过store://storeName命名空间前缀store.NamespacePrefix定义于 pkg/store/client.go区分于普通模型加载local-store后端会拒绝不带该前缀的加载请求避免模型加载器的贪婪自动探测把任意 LLM 模型误绑定到向量 store 上。端点详解Set / Get / Delete / FindSet写入键值对将若干向量与其对应值写入 storecurl -X POST http://localhost:8080/stores/set \ -H Content-Type: application/json \ -d {keys: [[0.1, 0.2], [0.3, 0.4]], values: [foo, bar]}语义要点重复 set 相同键等价于更新其值upsert 语义成功时返回200 OK 且无响应体源码对应c.NoContent(200)。Get按键取值curl -X POST http://localhost:8080/stores/get \ -H Content-Type: application/json \ -d {keys: [[0.1, 0.2]]}同时返回keys和values例如{keys:[[0.1,0.2]],values:[foo]}两个行为细节必须留意键的返回顺序不保留——不保证与请求顺序一致内部封装GetCols的注释也明确keys are sorted and will be returned in a different order不存在的键被静默跳过不会返回任何条目也不会报错。Delete删除键值对curl -X POST http://localhost:8080/stores/delete \ -H Content-Type: application/json \ -d {keys: [[0.1, 0.2]]}不存在的键会被直接忽略幂等成功时返回 200 OK 且无响应体。Find相似性检索curl -X POST http://localhost:8080/stores/find \ -H Content-Type: application/json \ -d {topk: 2, key: [0.2, 0.1]}topk限制返回条数响应结构与get相同但额外附带similarities数组1.0表示最大相似度完全一致结果按相似度从高到低排序。后端选择local-store默认与 valkey-store每个/stores/*请求都接受一个可选的backend字段来选择 store 实现。LocalAI 内置两种后端后端backend取值持久性说明Local默认local-store别名embedded-store内存重启即失精确余弦相似性零配置Valkey Searchvalkey-store别名valkey持久Valkey RDB/AOF由 Valkey SearchFT.*服务支撑重启不丢数据支持可选 HNSWembedded-store作为local-store的别名在 pkg/model/initializers.go 中注册embedded-store: LocalStoreBackendLocalStoreBackend local-store。默认的内存实现对应独立的 local-store 后端Go 编写的 gRPC 后端而valkey-store后端的完整实现位于 backend/go/valkey-store/其后端镜像在 backend/index.yaml 中以quay.io/go-skynet/local-ai-backends:latest-cpu-valkey-store等形式注册别名同样为valkey-store。valkey-store让向量在重启后存活valkey-store后端把向量持久化到一个带 Valkey Search 模块的服务端例如valkey/valkey-bundle镜像数据在 LocalAI 重启后依然保留——这是它与内存默认实现最本质的区别。在任意/stores/*请求中传入backend: valkey-store或别名valkey即可选用curl -X POST http://localhost:8080/stores/set \ -H Content-Type: application/json \ -d {backend: valkey-store, store: my-vectors, keys: [[0.1, 0.2], [0.3, 0.4]], values: [foo, bar]}连接与索引配置以 store 同名的模型 YAML连接参数和索引参数通过一个以 store 命名的模型配置来提供请求中的store字段就是该 store 的 model ID你只需在 models 目录下放一个name与 store 相同的 YAMLbackend: valkey-store并把连接/索引设置写进options:列表key:value字符串name: my-vectors backend: valkey-store options: - addr:valkey.internal:6379 - username_env:MY_VALKEY_USER - password_env:MY_VALKEY_PASSWORD - index_algo:HNSW - distance_metric:COSINE这种每个 store 独立解析自己配置的设计意味着同一个 LocalAI 进程内的不同 store 可以指向不同的 Valkey 服务器、使用不同的索引设置——这与StoreBackend按 store 名查配置的源码实现core/backend/stores.go完全对应。若某 store 没有配置后端将连接localhost:6379并使用下表的默认值零配置体验不受影响。选项全表选项默认值说明addrlocalhost:6379Valkey 服务器地址host:portusername(空)可选 ACL 用户名明文写在配置中password(空)可选密码 / ACL 密钥明文写在配置中username_env(空)存放用户名的环境变量名。推荐用于密钥——避免凭据落进模型 YAMLpassword_env(空)存放密码的环境变量名。推荐用于密钥tlsfalse启用 TLS许多托管部署的硬性要求tls_ca_cert(空)用于校验服务器证书的 PEM CA 包路径自签 / 私有 CA 场景tls_skip_verifyfalse跳过 TLS 证书校验不安全仅限测试client_namelocalai-valkey-storeCLIENT LIST中报告的连接名始终设置db0逻辑 Valkey DB 索引SELECT n。命名空间前缀本身已在共享 DB 上做了键空间隔离index_algoFLATFLAT精确默认或HNSW大规模语料用的近似最近邻hnsw_m16HNSW 图度仅index_algo:HNSW时生效hnsw_ef_construction200HNSW 构建期候选列表仅 HNSWhnsw_ef_runtime10HNSW 查询期候选列表仅 HNSWdistance_metricCOSINECOSINE默认、L2或IPrequest_timeout_ms5000单命令超时毫秒关于凭据管理有一个值得学习的设计username_env/password_env选项的值是环境变量的名字而非凭据本身这与cloud-proxy的api_key_env模式一致让不同 store 配置各自引用独立的环境变量凭据。直接写username/password仍向后兼容且两者同时设置时直连值优先。相似度语义跨后端的换算规则使用COSINE时返回的similarities与 local store 遵循同一约定1.0 完全一致-1.0 方向相反Valkey 内部返回的是余弦距离后端以similarity 1 - distance换算成相似度使用L2或IP时similarities中返回的是 Valkey 的原始分数L2下数值越小越接近排序方向与COSINE相反无论哪种度量结果始终按最近优先排序。三个重要的运维注意事项索引异步更新Valkey Search 在写入后异步更新向量索引set之后立刻find可能看不到新向量——需要短暂轮询或重试find直到预期结果出现。get与delete是同步操作不受影响。仅支持独立standaloneValkey Search当前后端目标是一个命名空间/模型对应一个服务器尚不支持 Valkey Cluster——跨分片的索引协调不在该后端范围内。TLS 默认关闭是风险点只要 Valkey 服务器不在localhost、或配置了password/username就应当设置tls:true否则凭据与向量明文过网。TLS 的 SNIServerName取自addr的主机部分因此域名和 IP 地址型端点都能正常做证书校验自签/私有 CA 用tls_ca_cert指向 PEM 包tls_skip_verify:true会完全关闭校验仅限本地测试。内部视角LocalAI 自己如何使用这套 Store API从源码结构看Stores 的 gRPC 层proto.StoresSetOptions、proto.StoresGetOptions、proto.StoresFindOptions、proto.StoresDeleteOptions被 pkg/store/client.go 封装后在 LocalAI 内部至少有两个消费方VectorStore路由缓存 / KNN 分类器core/backend/stores.go 的localVectorStore通过StoreBackend(loader, appConfig, cl, storeName, )获取后端SearchK即store.Find(ctx, be, vec, k)的包装并额外叠加了全局后端槽位限流AcquireGlobalBackendSlot与 backend trace 记录/api/backend-traces中可见每次 search/insert 的向量维度、命中相似度与耗时。InsertBatch/Delete是可选扩展能力供语料管理器批量上刷向量或整体清空语料时同步清掉活动索引。人脸识别/v1/face/register、/v1/face/identify、/v1/face/forget直接构建在通用 store 之上把人脸 embedding 当作向量键、身份元数据当作值进行存取与 1:N 检索。小结与实践建议Stores 是低层 API只有set/get/delete/find四个操作列式返回、键等长、值与键一一对应默认local-store零配置、精确检索但数据随进程消失需要持久化与近似索引时切valkey-store用store 同名 YAML options列表做 per-store 的连接与索引配置valkey-store写入后索引异步可见find需要容忍短暂的重试窗口生产环境务必启用tls并用*_env选项管理凭据若你的目标是完整 RAG建议把 Stores 当作嵌入检索这一环节的构件而非直接对外的最终检索层。关键源码入口HTTP 端点实现、请求/响应结构体、后端解析与 VectorStore、gRPC 客户端封装、路由注册、valkey-store 后端实现、原文档。【免费下载链接】LocalAILocalAI is the open-source AI engine. Run any model - LLMs, vision, voice, image, video - on any hardware. No GPU required.项目地址: https://gitcode.com/GitHub_Trending/lo/LocalAI创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考