LocalAI Embeddings 实战指南：从模型接入到对话级 Go 侧 Pooling

LocalAI Embeddings 实战指南从模型接入到对话级 Go 侧 Pooling【免费下载链接】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 的 Embeddings 能力让任意本地文本模型llama.cppGGUF、bert.cpp、HuggingFacesentence-transformers通过一条 OpenAI 兼容的/v1/embeddings接口统一输出文本/Token 向量并额外扩展出整段聊天对话嵌入与请求级 Go 侧 pooling能力可直接支撑 RAG 检索、向量存储与语义路由等场景。本文以仓库内文档 docs/content/features/embeddings.md 为核心脉络结合 core/backend/embeddings.go、core/backend/pooling.go 与 core/http/endpoints/openai/embeddings.go 等源码实现帮助你完整掌握模型接入、请求构造、Pooling 选型与常见故障排查。功能概览本地推理引擎的通用向量出口LocalAI 支持为一段文本或一组 token生成 embeddings接口语义对齐 OpenAI 的 Embeddings API 功能——它产出 512 维、L2 归一化、专为面部相似度比对的向量与本文通用的文本 embedding 属于两条不同的技术栈。模型兼容性从源码结构看embedding 请求最终由 ModelEmbedding 分发到已加载模型的 gRPC 后端因此后端只需实现EmbeddingsRPC 即可接入。当前embeddings路径兼容的后端包括llama.cpp模型GGUFllama-cpp后端bert.cpp模型HuggingFace 上的 sentence-transformers 模型sentencetransformers后端方式一使用 Gallery 内置模型推荐LocalAI 的模型画廊Model Gallery见 Model Gallery预置了配置好的 embedding 模型。在 gallery/index.yaml 中可以看到典型的qwen3-embedding-*条目例如qwen3-embedding-4b的关键定义- name: qwen3-embedding-4b urls: - https://huggingface.co/Qwen/Qwen3-Embedding-4B-GGUF overrides: embeddings: true parameters: model: Qwen3-Embedding-4B-Q4_K_M.gguf files: - filename: Qwen3-Embedding-4B-Q4_K_M.gguf使用 Gallery 模型的步骤只有两步确认模型已在画廊中可用通过local-ai models list或 Model Gallery 检查在 API 调用中直接使用模型名画廊内置的示例 embedding 模型有qwen3-embedding-4b— Qwen3 Embedding 4Bqwen3-embedding-8b— Qwen3 Embedding 8Bqwen3-embedding-0.6b— Qwen3 Embedding 0.6B示例从 Gallery 使用 Qwen3-Embedding-4Bcurl http://localhost:8080/embeddings -X POST -H Content-Type: application/json -d { input: My text to embed, model: qwen3-embedding-4b, dimensions: 2560 }其中dimensions用于指定输出维度Qwen3-Embedding-4B 支持 322560 范围不传则使用模型默认维度。画廊条目通过overrides.embeddings: true预先声明该模型可用于 embedding模型文件则按 gallery/index.yaml 中记录的sha256与uri从 HuggingFace 拉取无需手工书写任何 YAML。方式二手动配置模型 YAML如果你已有本地模型文件在models目录新建一个 YAML 配置文件即可。核心是三个字段API 使用的模型名name、模型文件parameters.model、后端标识backend并显式设置embeddings: truename: text-embedding-ada-002 # The model name used in the API parameters: model: model_file backend: backend embeddings: trueembeddings: true缺失是文档中列出的最常见配置错误详见下文故障排查。backend的取值决定走哪条 embedding 链路下面分后端展开。HuggingFace / sentence-transformers 嵌入要使用sentence-transformers及 HuggingFace 上的向量模型指定sentencetransformers后端name: text-embedding-ada-002 backend: sentencetransformers embeddings: true parameters: model: all-MiniLM-L6-v2parameters.model直接填 HuggingFace 上的模型标识如all-MiniLM-L6-v2模型会在首次调用 API 时自动下载无需预下载。该后端基于 Python 的 sentence-transformers 生态仓库侧自动识别逻辑见 core/gallery/importers/sentencetransformers.go只要 HuggingFace 仓库包含modules.jsonST 流水线清单或sentence_bert_config.json旧版标记或作者为sentence-transformers就会被路由到sentencetransformers后端并自动生成embeddings: true的配置。注意使用该后端有几点前提sentencetransformers是 LocalAI 的可选 Python 后端。若运行官方容器通常已内置就绪本地执行则须在EXTERNAL_GRPC_BACKENDS环境变量中显式声明它例如EXTERNAL_GRPC_BACKENDSsentencetransformers:/path/to/LocalAI/backend/python/sentencetransformers/sentencetransformers.py该后端只支持嵌入文本不支持嵌入 token。需要嵌入 token 时请改用bert后端或llama.cpp后端。llama.cpp 嵌入llama-cpp后端同样支持 embeddings但必须开启embeddings: truename: my-awesome-model backend: llama-cpp embeddings: true parameters: model: ggml-file.bin然后调用/embeddings或 OpenAI 兼容的/v1/embeddings即可curl http://localhost:8080/embeddings -X POST -H Content-Type: application/json -d { input: My text, model: my-awesome-model } | jq .底层链路为HTTP 端点构造modelConfig.InputStrings→ backend.ModelEmbedding 经loader.Load取出模型 → 调用 gRPC 后端的EmbeddingsRPC → 由 finishEmbeddingResult 根据返回结果的布局layout做终处理。处理结果随后由 EmbeddingsEndpoint 组装成标准 OpenAI 响应同时支持encoding_formatbase64将 float32 向量按小端序打包为 base64 字符串返回Node.js SDK v4 默认即此格式。嵌入聊天对话与 Go 侧 Pooling/v1/embeddings是 LocalAI 的OpenAI 兼容扩展端点除了input它还接受一段完整的对话messages并支持请求级的pooling方案——由 LocalAI 自身Go 层把后端返回的逐 token 原始向量归约成一个向量curl http://localhost:8080/v1/embeddings -X POST -H Content-Type: application/json -d { model: my-awesome-model, messages: [ {role: system, content: You are a support agent.}, {role: user, content: My invoice is wrong.} ], pooling: decayed_mean, pooling_half_life_tokens: 256 }该扩展的行为约束如下每个请求只能携带一段对话响应仍是标准 OpenAI embeddings 形态包含单个data[0].embedding项input与messages互斥同时出现返回 400未知的pooling取值同样返回 400校验逻辑见 ValidatePooling若模型配置同时带有template.chat与template.chat_message对话会像 chat 提示词一样被完整渲染使 embedding 与 chat 模型实际看到的内容完全一致渲染入口见 embeddings.go 的evaluator.RenderConversationForEmbedding否则使用固定的角色前缀兜底按换行拼接role: content跳过空内容消息消息中的图片、音频、视频等非文本内容一律忽略。Pooling 方案对照表pooling决定如何把逐 token 向量归约成单个 embedding值含义(空)/backend由后端自行 pooling——这是默认值即历史上完全一致的行为mean对所有 token 向量求平均last取最后一个 token 的向量decayed_mean按时间加权平均第i个 token共T个权重为2^(-(T-1-i)/H)半衰期Hpooling_half_life_tokens默认 256——近期内容占主导同时不会抹掉更早的上下文Go 侧方案的三种实现对应 core/backend/pooling.gopoolMean用 float64 累加求平均poolLast复制末位 token 向量poolDecayedMean用math.Exp2计算指数衰减权重后加权平均半衰期 0 时回退到默认值 256见常量 DefaultPoolingHalfLifeTokens。具体调用路径为 PoolEmbeddingResult其先通过 reshapeEmbeddings 把 gRPC 按行主序打包的扁平 float 载荷还原为tokens × dim矩阵再执行归约与归一化。布局声明与兼容性规则Go 侧 pooling 需要后端返回逐 token 原始向量因此每个后端都要在EmbeddingResult中声明结果是最终向量还是逐 token 矩阵LocalAI 在遇到请求 Go 侧方案但后端返回最终向量或请求backend透传但后端返回逐 token 矩阵时直接拒绝绝不依据向量形状去猜测形状不可靠1 个 token 的原始向量与 1 个最终向量都是1 × dim对应错误类型与提示见 finishEmbeddingResult不声明布局的旧后端仅兼容backendpoolingllama.cpp 在模型加载时就决定了布局当模型配置了 Go 侧parameters.pooling方案时LocalAI 会自动追加后端选项pooling:none原始逐 token 加载见 core/config/pooling_config_test.go 中对SetDefaults的断言。该实例可在mean、last、decayed_mean之间按请求切换但不能切回backendpooling需重新加载模型反之后端 pooling 的 llama.cpp 实例会拒绝请求级 Go pooling。模型加载期的双向配置一致性检查位于 model_config.go若后端显式返回逐 token 向量其他后端也可能支持 Go 侧 pooling。归一化与 llama.cpp 完全一致的embd_normalizeGo 侧 pooling 完成后向量会按 llama.cpp 的embd_normalize规则归一化。由于pooling:none下 llama.cpp 只输出未归一化的原始向量服务端只归一化它自己 pooling 的结果LocalAI 在 Go 层实现了对 llama.cppcommon_embd_normalize的逐位移植见 normalizeEmbeddingembdNorm 0不归一化embdNorm 0按最大绝对值缩放并除以 32760.0 对齐 int16 范围embdNorm 2默认L2/欧氏归一化其他值p-范数1 为曼哈顿。归一化系数通过模型配置中的options: [embd_normalize:n]控制别名embedding_normalize:n解析逻辑 embdNormalizeFromOptions 默认返回 2不可解析的值会被静默忽略——与 llama.cpp 后端吞掉std::stoi失败的行为保持一致。模型级默认配置池化方案同样可以在模型 YAML 的parameters:中固化请求级参数会覆盖之两者共用同一套 ValidatePooling 校验且pooling_half_life_tokens只在pooling: decayed_mean时被允许name: conversation-embedder backend: llama-cpp embeddings: true parameters: model: ggml-file.bin pooling: decayed_mean pooling_half_life_tokens: 256需要提醒的是Go 侧 pooling 依赖能上报 embedding 布局的新版后端旧后端对 Go 侧方案会失败关闭fail closed直接返回要求重建或升级后端的错误而不是静默给出错误向量。应用示例LLamaIndex 检索将 LLamaIndex 与 LocalAI 组合用作 embedding 的完整示例见仓库外维护的mudler/LocalAI-examples项目中query_data目录使用该脚本/数据端配合本接口即可搭建本地 RAG 检索链路。常见问题与故障排查问题一Embedding 模型返回结果不正确症状模型返回空向量或错误向量调用 embedding 端点时报错。常见原因与处置模型文件名错误确保使用了画廊或本地模型文件位置的正确文件名。画廊模型有固定的文件名例如Qwen3-Embedding-4B-Q4_K_M.gguf可对照 Model Gallery 或 gallery/index.yaml 核实。上下文尺寸不匹配确保context_size不超过模型最大上下文Qwen3-Embedding-4B最大 32k32768Qwen3-Embedding-8B最大 32k32768Qwen3-Embedding-0.6B最大 32k32768缺少embeddings: true模型配置必须显式开启该标志。正确配置示例name: qwen3-embedding-4b backend: llama-cpp embeddings: true context_size: 32768 parameters: model: Qwen3-Embedding-4B-Q4_K_M.gguf问题二维度不匹配症状返回的 embedding 维度与预期不一致。解决方案在 API 请求中使用dimensions参数指定输出维度。Qwen3-Embedding 系列支持 32 到最大维度之间的任意取值4B 最大 25608B 最大 4096。curl http://localhost:8080/embeddings -X POST -H Content-Type: application/json -d { input: My text, model: qwen3-embedding-4b, dimensions: 1024 }问题三模型未找到症状API 返回 404 或 model not found。解决方案确认模型已在 models 目录正确配置请求中的模型名必须与配置中的name字段完全一致端点会校验请求model是否为空并据其加载配置见 EmbeddingsEndpoint对画廊模型确认画廊已正确加载。Qwen3 Embedding 系列模型规格Qwen3 Embedding 系列在 gallery/index.yaml 中有完整收录其关键特性如下模型参数量最大上下文最大维度支持语言qwen3-embedding-0.6b0.6B32k1024100qwen3-embedding-4b4B32k2560100qwen3-embedding-8b8B32k4096100全部模型共同支持用户自定义输出维度32 到各自最大维度多语言文本嵌入100 种语言含各编程语言的跨语言/代码检索能力基于指令调优的 embedding——可通过自定义指令针对特定任务、语言或场景增强效果。画廊为各规格默认配置的量化文件与校验信息可在 gallery/index.yaml 中核对0.6B 提供Q8_0/f164B/8B 提供Q4_K_M至f16等多种量化。小结在 LocalAI 中接入文本 embedding 是一条清晰而灵活的路径画廊模型零配置起步、手动 YAML 支持按后端定制、sentencetransformers覆盖 HuggingFace Python 生态、llama-cpp主打 GGUF 高性能本地推理。而/v1/embeddings的messages 请求级pooling扩展更是把对话语义向量化做成了开箱即用的能力——配合模型级默认值与 llama.cpp 对齐的embd_normalize归一化无论做 RAG 检索、向量库写入还是语义路由都能拿到行为可预期、与 OpenAI 兼容的稳定向量结果。【免费下载链接】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），仅供参考