在 Xinference 中部署 m3e-small 文本嵌入模型：规格、启动与调用实践

在 Xinference 中部署 m3e-small 文本嵌入模型规格、启动与调用实践【免费下载链接】inferenceSwap GPT for any LLM by changing a single line of code. Xinference lets you run open-source, speech, and multimodal models on cloud, on-prem, or your laptop — all through one unified, production-ready inference API.项目地址: https://gitcode.com/GitHub_Trending/in/inference导读m3e-small 是内置在 Xinference 中的轻量级中英文文本嵌入embedding模型以 512 维向量输出、512 token 上下文上限著称适用于中文语义检索、文本相似度计算与向量化入库等场景。本文以 m3e-small 内置模型文档 为主线结合仓库中的模型注册表与 embedding 引擎源码讲解其规格参数、单条命令启动方式以及通过 Xinference Client 与 OpenAI 兼容 API 完成向量化调用的完整流程。m3e-small 模型速览m3e-small 由 moka-ai 开源在 Xinference 中被注册为内置builtinembedding 模型。根据官方内置模型文档其核心属性如下属性值Model Namem3e-smallLanguageszh中文、en英文AbilitiesembedDimensions512Max Tokens512Model IDmoka-ai/m3e-smallModel HubsHugging Facemoka-ai/m3e-small、ModelScopeAI-ModelScope/m3e-small512 维向量每个输入文本被编码为一个 512 维的稠密向量维度适中既能保证语义区分度又不会给向量数据库和内存带来过大压力适合中小规模知识库场景。512 token 上限单次输入最长 512 token超出部分将被截断下文会结合源码说明截断逻辑因此更适合段落级而非超长文档级的编码。中英双语同时支持中文与英文输入无需在中文和英文场景间切换模型。从仓库的内置模型注册表 xinference/model/embedding/model_spec.json 可以确认该模型的完整元数据model_format为pytorchHugging Face 侧模型 ID 为moka-ai/m3e-smallrevision44c696631b2a8c200220aaaad5f987f096e986dfModelScope 侧为AI-ModelScope/m3e-small二者量化方式均为none即原精度加载不做额外量化。该模型页面的生成机制值得说明的是doc/source/models/builtin/embedding/目录下的模型页面由 doc/templates/embedding.rst.jinja 模板自动生成模板直接引用model_name、dimensions、max_tokens、language、model_id、model_hubs等字段——也就是说上述规格表与model_spec.json中的注册数据一一对应读者修改或新增内置 embedding 模型时只需更新模型注册表文档字段会随之保持一致。一条命令启动 m3e-small按官方文档在 Xinference 中启动 m3e-small 只需一条命令xinference launch --model-name m3e-small --model-type embedding要点说明--model-name m3e-small指定内置模型名称与模型注册表中的model_name严格对应--model-type embedding指定模型类型为 embedding区别于llm、image、rerank等类型该参数对 embedding 模型是必需的。首次启动时Xinference 会从模型仓库默认 Hugging Face也可通过--download-hub modelscope切换为 ModelScope下载权重并缓存到本地之后启动会直接复用本地缓存。启动背后发生了什么从源码看xinference launch最终会走create_embedding_model_instance()工厂见 xinference/model/embedding/core.py核心步骤包括匹配模型族通过match_embedding(model_name, model_format, quantization, download_hub)在注册表中定位m3e-small的EmbeddingModelFamilyV2描述包含dimensions512、max_tokens512、language[zh,en]缓存权重EmbeddingCacheManager负责检查缓存目录并按需下载模型文件选择推理引擎embedding 模型默认使用sentence_transformers引擎源码注释明确指出“we use sentence_transformers as the default engine for all models”在启用虚拟环境virtual env模式下还会通过check_engine_by_model_name_and_engine_with_virtual_env()为模型准备独立的依赖环境实例化模型将model_uid、model_path、模型族、量化方式等传入SentenceTransformerEmbeddingModel随后加载完成。m3e-small在注册表中只声明了pytorch格式因此它始终走 sentence_transformers / transformers 的 PyTorch 加载路径而不是 llama.cppGGUF或 vLLM 引擎。模型规格的深层含义Dimensions输出维度与 Max Tokens输入上限的作用dimensions512直接决定返回向量数组的长度也是向量库建索引时dim字段的取值依据max_tokens512是模型可处理的最大输入长度。Xinference 的 EmbeddingModel 基类提供了与 vLLM LLM 语义对齐的truncate_prompt_tokens截断机制见 xinference/model/embedding/core.pyNone不截断 0按指定 N 个 token 截断 0显式空输入max_length0 0回退到模型自身的max_tokens即 m3e-small 的 512。截断采用“结构保持”策略str/List[str]按 token 截断token 数组直接切片多模态字典仅截断text字段而保留媒体字段在 llama.cpp 等无 Python tokenizer 的引擎或 tokenizer 调用失败时会降级为字符级截断默认约 4 字符/token可用环境变量XINFERENCE_EMBEDDING_TRUNCATE_CHAR_PER_TOKEN调整。这意味着向 m3e-small 提交超长文本时服务不会报错而是按上限安全截断后返回向量。引擎选择与依赖model_spec.json中为 m3e-small 声明了如下 virtualenv 依赖按引擎条件安装sentence_transformers 引擎sentence-transformers及其依赖、系统 torchvision 与 torchvllm 引擎vLLM 依赖与系统 numpy。因此m3e-small 既可以在默认的 sentence_transformers 引擎下运行也保留了 vLLM 引擎的兼容路径。若关闭虚拟环境XINFERENCE_ENABLE_VIRTUAL_ENV未开启则需要宿主环境预先安装sentence-transformers版本需高于 3.1.0见 xinference/model/embedding/sentence_transformers/core.py 中的版本检查。调用 m3e-small 生成向量模型启动后可以通过两条主流路径调用。方式一Xinference Clientfrom xinference.client import Client client Client(http://localhost:9997) model_uid client.launch_model(model_namem3e-small, model_typeembedding) model client.get_model(model_uid) result model.create_embedding(今天天气怎么样) print(result[data][0][embedding]) # 512 维浮点向量 print(result[usage])返回结构为 OpenAI 风格{ object: list, model: model_uid, data: [{index: 0, object: embedding, embedding: [...512 个浮点数...]}], usage: {prompt_tokens: N, total_tokens: N} }create_embedding支持字符串、字符串列表等多种输入形态底层由 xinference/api/routers/embeddings.py 将请求路由到POST /v1/embeddings并经过 EmbeddingModel 的create_embedding统一入口xinference/model/embedding/core.py。值得留意的是该入口还实现了批量合并逻辑多个并发调用会按 kwargs 分组、合并成一个大 batch 交给引擎编码再按原始索引切分返回从而提升吞吐引擎实际编码时默认normalize_embeddingsTrueL2 归一化返回的向量可直接用点积计算余弦相似度。方式二OpenAI 兼容 APIXinference 提供 OpenAI 兼容的/v1接口任何支持 OpenAI Embedding API 的客户端都可以直接对接无需显式指定引擎细节import openai # 假设 m3e-small 已启动model_uid 已知api_key 任意非空字符串即可 client openai.Client(api_keynot empty, base_urlhttp://localhost:9997/v1) resp client.embeddings.create(modelmodel_uid, input[今天天气怎么样, how is the weather]) print(resp.data[0].embedding) # 512 维向量也可以直接用 curlcurl -X POST http://localhost:9997/v1/embeddings \ -H Content-Type: application/json \ -d {model: m3e-small, input: 今天天气怎么样}注意当启用认证时/v1/embeddings路由需要models:read权限 scope见 xinference/api/routers/embeddings.py需在请求中携带有效 token。常用辅助命令查看当前已注册的内置 embedding 模型列表xinference registrations -t embedding输出包含Type / Name / Language / Dimensions / Is-builtin等列可确认 m3e-small 已注册且Dimensions为 512。查看 m3e-small 的版本信息含本地缓存位置与缓存状态xinference describe --model-name m3e-small --model-type embedding版本标识的组成为模型名--max_tokens--dimensions--model_format--quantization见 xinference/model/embedding/core.py对 m3e-small 即为m3e-small--512--512--pytorch--none形态可用于区分不同配置的模型实例。典型应用场景结合 m3e-small 的规格特点它适合以下场景中文语义检索 / RAG 向量化将知识库文本切分为不超过 512 token 的段落用 m3e-small 生成 512 维向量写入向量数据库查询时对用户问题做同模型编码后做向量相似度检索文本相似度计算利用返回向量已做 L2 归一化的点积快速计算相似度用于去重、聚类或推荐轻量级部署模型尺寸小、维度适中对 CPU/低显存环境友好适合边缘或成本敏感场景。对于需要更高精度或更长上下文的场景可在同一内置 embedding 家族中选择更大规格的模型如注册表中同族的m3e-base768 维调用方式与本文完全一致仅需更换--model-name。小结本文从 m3e-small 内置模型文档 出发完整覆盖了模型规格、启动命令、引擎加载链路与两种调用方式。核心要点回顾启动命令xinference launch --model-name m3e-small --model-type embedding规格512 维、512 token、中英双语、pytorch 格式、无量化默认引擎为 sentence_transformers支持 OpenAI 兼容接口返回的向量默认 L2 归一化超长输入由truncate_prompt_tokens机制安全截断不会导致服务报错。如需进一步了解 Xinference embedding 模型的架构细节可继续阅读 xinference/model/embedding/core.pyEmbeddingModel 基类与批量逻辑、xinference/model/embedding/sentence_transformers/core.py默认引擎实现以及模型注册表 xinference/model/embedding/model_spec.json。【免费下载链接】inferenceSwap GPT for any LLM by changing a single line of code. Xinference lets you run open-source, speech, and multimodal models on cloud, on-prem, or your laptop — all through one unified, production-ready inference API.项目地址: https://gitcode.com/GitHub_Trending/in/inference创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考