Xinference 文本嵌入完全指南Embeddings API、多引擎服务与多模态 WeMM 输入【免费下载链接】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本文围绕 Xinference 的 Embeddings API 展开系统讲解文本嵌入的核心概念、OpenAI 兼容的/v1/embeddings接口、四种服务引擎sentence_transformers / vllm / flag / llama.cpp的选择依据、truncate_prompt_tokens截断机制以及 WeMM-Embedding 的多模态输入方式。读完本文你将掌握通过 cURL、OpenAI Python Client 和 Xinference Python Client 三种方式创建文本与多模态向量并能按检索、分类、聚类等场景正确配置引擎与参数。什么是文本嵌入Text Embeddings文本嵌入Text Embedding将一段文本映射为一个浮点数向量用于量化不同文本之间的语义相关程度。向量之间的距离是文本相似度的直接指标距离越小、相关性越高距离越大、相关性越低。这一能力支撑着搜索、聚类、推荐、异常检测、多样性测量与分类等一系列上层应用。在 Xinference 中嵌入模型通过 Embeddings API 对外提供服务。该 API 完全模仿 OpenAI 的 Create Embeddings 接口语义端点对应关系如下APIOpenAI 兼容端点Embeddings APIPOST /v1/embeddings在路由层面该端点由 xinference/api/routers/embeddings.py 注册到 FastAPI 路由表启用认证后要求models:read权限同一文件中还注册了POST /v1/convert_ids_to_tokens用于将 token id 序列解码回 token 文本便于调试分词结果。请求处理入口位于 xinference/api/restful_api.py服务端解析请求体中的model、input等字段将其余参数透传给底层模型实例的create_embedding并把返回的Embedding对象直接序列化为 JSON 响应。支持的模型Xinference 内置了一批开箱即用的嵌入模型涵盖常见中英文场景。全部内置嵌入模型清单可在文档 内置嵌入模型索引 中查看该索引由 embedding_index.rst.jinja 模板生成与模型描述文件同步维护。从源码结构看内置模型以EmbeddingModelFamilyV2的形式注册在 xinference/model/embedding/embed_family.py 的BUILTIN_EMBEDDING_MODELS与EMBEDDING_ENGINES两张注册表中每个模型家族声明了dimensions输出维度、max_tokens最大输入长度、language支持语言以及可选的额外模态能力model_abilityvision/video/audio其定义见 xinference/model/embedding/core.py。match_embedding会依据模型名、模型格式与量化方式完成匹配并支持从 ModelScope 下载当设置了download_hubmodelscope或环境变量启用 ModelScope 时优先选择 ModelScope 的 model spec。除内置模型外用户也可以在 Xinference 中注册自定义嵌入模型参见 自定义模型文档注册后同样进入上述匹配流程。选择服务引擎四种 embedding 引擎详解启动嵌入模型时通过model_engine参数命令行使用--model-engine指定服务引擎sentence_transformers默认引擎适用于全部嵌入模型。底层基于 Sentence-Transformers 框架加载 PyTorch 模型也是向后兼容性最好的选择。从 xinference/model/embedding/core.py 的实现可以看到当model_engine未指定时Xinference 会显式回退到sentence_transformers与 LLM 的默认行为不同这是嵌入模块特意保留的兼容策略。该引擎要求sentence-transformers3.1.0加载时默认对输出向量执行 L2 归一化normalize_embeddingsTrue便于下游直接使用点积代替余弦相似度相关实现见 xinference/model/embedding/sentence_transformers/core.py。vllm高吞吐服务引擎适用于名称以bge、gte、text2vec、m3e、Qwen3、WeMM、bce开头的模型家族例如bce-embedding-base_v1。模型前缀白名单定义于 xinference/model/embedding/vllm/core.py适合高并发在线检索场景。flag基于 FlagEmbedding 的引擎其核心价值在于支持混合检索hybrid retrieval可通过额外参数return_parseTrue同时获得稠密向量dense与稀疏向量sparse详见下文 FAQ 小节。llama.cpp服务于 GGUF 格式的嵌入模型对应LlamaCppEmbeddingSpecV1model_formatggufv2的模型规范。引擎与模型家族的匹配校验在 xinference/model/embedding/embed_family.py 的check_engine_by_model_name_and_engine及其虚拟环境版本中完成若目标模型不支持指定引擎启动时会直接抛出Model xxx cannot be run on engine xxx的明确报错。嵌入模型还支持通过 虚拟环境 隔离引擎依赖此时可通过virtualenv标记绕过引擎兼容性检查。控制输入长度truncate_prompt_tokens 截断机制Embeddings API 接受可选的truncate_prompt_tokens参数在编码前限制每个输入的 token 长度不设置 /null不进行截断正整数N将每个输入截断到至多N个 token-1截断到模型自身的最大输入长度即模型家族的max_tokens。使用示例curl -X POST \ http://XINFERENCE_HOST:XINFERENCE_PORT/v1/embeddings \ -H Content-Type: application/json \ -d { model: MODEL_UID, input: A very long document ..., truncate_prompt_tokens: 512 }截断的底层实现该参数的处理逻辑位于 xinference/model/embedding/core.py 的_truncate_sentences语义与 vLLM LLM 保持一致0封顶到 N 个 token0表示显式空输入max_length00则回退到模型自身的max_tokens当模型没有声明max_tokens时0会安全地放弃截断而非报错。截断是结构保持的_truncate_value见 xinference/model/embedding/core.py纯 token 数组List[int]/List[List[int]]按 token id 直接切片多模态字典Dict只截断其中的text字段image/video/audio等媒体字段原样保留——因为媒体字段可能是 URL、文件路径或 base64 载荷截断它们会直接损坏媒体数据普通字符串优先走 tokenizer 做 token 级截断_truncate_text若 tokenizer 调用失败如 llama.cpp 引擎没有 Python tokenizer则降级为字符级截断每 token 按约 4 个字符估算可通过环境变量XINFERENCE_EMBEDDING_TRUNCATE_CHAR_PER_TOKEN调整默认 4。该路径保证服务不会因截断失败而中断。该机制同时覆盖单条请求与批量请求create_embedding是extensible批处理方法批量模式下会先按 kwargs 哈希分组、再在组内统一截断最后按原始调用顺序还原index实现见 xinference/model/embedding/core.py。仓库中 test_truncate_prompt_tokens.py 对上述多种输入形态字符串、token 数组、多模态字典均有覆盖。内存占用控制为避免长文档批量编码引发显存 OOM嵌入模型在累计处理 token 数达到阈值时会主动清理缓存XINFERENCE_EMBEDDING_EMPTY_CACHE_COUNT默认 10 次调用或XINFERENCE_EMBEDDING_EMPTY_CACHE_TOKENS默认 8192 token任一条件满足即触发gc.collect()与显存释放见 xinference/model/embedding/core.py。多模态嵌入WeMM-Embedding 输入格式WeMM-Embedding 模型家族名称以WeMM-Embedding-开头接受文本、图像、视频、视觉文档以及交错多模态输入不支持音频。可用引擎为sentence_transformers默认与vllm。前者要求sentence-transformers5.7.0、transformers5.2.0与qwen-vl-utils0.0.14后者要求 vLLM 版本适配详见 xinference/model/embedding/sentence_transformers/core.py 与 xinference/model/embedding/vllm/core.py。输入形式一扁平字典一个扁平的输入字典可以包含任意有序组合的text、image与video字段。例如xinference launch \ --model-name WeMM-Embedding-2B \ --model-type embedding \ --model-engine sentence_transformers curl -X POST \ http://XINFERENCE_HOST:XINFERENCE_PORT/v1/embeddings \ -H Content-Type: application/json \ -d { model: MODEL_UID, input: { role: user, content: [ {type: image_url, image_url: {url: https://example.com/image.jpg}}, {type: text, text: Find content related to this image.}, {type: video_url, video_url: {url: https://example.com/video.mp4}} ] }, dimensions: 256 }输入形式二role / content 消息与交错排列若需要精确控制模态的排列顺序可传入role/content消息结构{role: user, content: [...]}其中content中的每一项为{type: image_url | video_url | text, ...}的字典image_url与video_url内容项同样被接受。此外也支持{messages: [...]}形式表达多轮消息会话。这些输入会被归一化为 WeMM 的对话消息格式归一化逻辑包括对音频输入的显式拒绝、对image_url/video_url的 URL 提取位于 xinference/model/embedding/wemm.py 的normalize_wemm_messages/normalize_wemm_inputs。注意本地媒体路径指向的是 Xinference 服务器上的文件。输出维度Matryoshka 维度选择请求中的dimensions参数用于选择模型支持的 Matryoshka嵌套向量维度之一。默认情况下Xinference 会对输出向量做维度截断并再次执行 L2 归一化在 sentence_transformers 引擎中dimensions会映射为底层truncate_dim见 xinference/model/embedding/sentence_transformers/core.py并对非法的 Matryoshka 维度抛出校验错误matryoshka_dimensions定义于模型 config在 vLLM 引擎中WeMM 嵌入通过池化参数与 chat template 实现见 xinference/model/embedding/vllm/core.py。视频输入方面当qwen-vl-utils的 torchvision 视频读取器不可用时Xinference 会自动安装 PyAV 回退读取器VIDEO_READER_BACKENDS[torchvision]替换见 xinference/model/embedding/wemm.py。快速上手三种方式调用 Embeddings API下面分别用 cURL、OpenAI Python Client 与 Xinference Python Client 创建文本向量。前提是已通过xinference launch启动一个嵌入模型并拿到它的模型 UIDMODEL_UID。方式一cURLcurl -X POST \ http://XINFERENCE_HOST:XINFERENCE_PORT/v1/embeddings \ -H accept: application/json \ -H Content-Type: application/json \ -d { model: MODEL_UID, input: What is the capital of China? }方式二OpenAI Python Client由于接口与 OpenAI 兼容只需将base_url指向 Xinference 的/v1即可无缝切换import openai client openai.Client( api_keycannot be empty, base_urlhttp://XINFERENCE_HOST:XINFERENCE_PORT/v1 ) client.embeddings.create( modelmodel_uid, input[What is the capital of China?] )方式三Xinference Python Client使用官方 Python 客户端xinference包时可以像调用本地模型一样操作from xinference.client import Client client Client(http://XINFERENCE_HOST:XINFERENCE_PORT) model client.get_model(MODEL_UID) input What is the capital of China? model.create_embedding(input)响应格式三种方式返回的 JSON 结构一致OpenAI 风格{ object: list, model: MODEL_UID, data: [{ index: 0, object: embedding, embedding: [ -0.014207549393177032, -0.01832585781812668, ... -0.03009396605193615, 0.05420297756791115] }], usage: { prompt_tokens: 37, total_tokens: 37 } }响应中的data[].embedding即为浮点向量usage.prompt_tokens统计本次输入消耗的 token 数。从源码实现看xinference/model/embedding/sentence_transformers/core.pytoken 统计通过对 batch 中attention_mask求和得到多模态输入如 CLIP、jina-embeddings-v4则统计input_ids/pixel_values的元素总数而 flag 引擎当前以prompt_tokens-1占位xinference/model/embedding/flag/core.pyvLLM 引擎与部分多模态路径的 token 统计也类似。批量传入多个字符串时data数组会按输入顺序返回对应数量的向量。进阶用法与 FAQ为什么 LLM 不提供 Embeddings API不提供。出于性能考虑Xinference 没有为 LLM 提供 embed 接口。嵌入任务应使用专门的嵌入模型而非通用 LLM。如何集成 LangChain可以。LangChain 官方文档提供了 Xinference 的 Text Embedding Models 集成章节LangChain 官方 Xinference 文档中的 Text Embedding Models: Xinference可直接参考其集成方式。Xinference 的 Embeddings API 与 OpenAI 兼容也可通过 LangChain 的 OpenAI Embeddings 封装快速接入。仓库内 xinference/model/embedding/core.py 的_fix_langchain_openai_inputs专门处理了 LangChain OpenAI 客户端可能传入的 token id 二维数组输入会先解码回字符串再编码保证集成路径下输入被正确理解。如何获取稀疏向量混合检索支持。使用flag引擎部署模型后调用 Embeddings API 时设置额外参数return_parseTrue对应源码中的return_sparse即可同时返回稀疏向量。此时响应的object为sparse_embeddingembedding字段为{token_id: weight}形式的稀疏字典见 xinference/model/embedding/flag/core.py可直接用于 BM25 风格的稀疏检索与稠密向量组成混合检索hybrid retrieval流水线。需要注意的是return_sparse仅受flag引擎支持若在sentence_transformers引擎下传入该参数会抛出 please use flag instead 的明确错误见 xinference/model/embedding/sentence_transformers/core.py。如何为 Jina 系列模型指定检索任务对于 jina-embeddings-v3/v4/v5 模型sentence_transformers 引擎会解析可选的task参数v3task映射为prompt_name如retrieval.query/retrieval.passagev4task直接透传给模型的forward()v5task透传给模型的encode()且当调用方未传task时默认回退到retrieval保证 OpenAI 风格的客户端无需感知该参数也能正常工作。任务白名单与别名映射定义于 xinference/model/embedding/sentence_transformers/core.py传入非法task会返回含合法取值列表的清晰报错。服务端处理长文档的性能建议结合上述机制服务超长文档时建议优先通过truncate_prompt_tokens在服务端统一截断避免每次请求都携带超长 payload批量请求由create_embedding的批处理路径自动按 kwargs 分组合并计算xinference/model/embedding/core.py多条相同参数的请求会合并为一次编码、显著提升吞吐同时注意XINFERENCE_EMBEDDING_EMPTY_CACHE_*环境变量对缓存清理频率的影响在显存紧张的设备上可适当调低阈值。总结Xinference 的 Embeddings API 以 OpenAI 兼容的/v1/embeddings端点统一了文本与多模态向量服务sentence_transformers作为默认引擎覆盖全部模型vllm面向高吞吐场景flag提供稀疏稠密混合检索能力llama.cpp服务 GGUF 模型truncate_prompt_tokens提供了从「不截断」到「封顶 N token」再到「模型上限」的完整控制并且对多模态输入做结构保持的文本字段截断WeMM-Embedding 家族进一步将图像、视频与文本交织输入纳入同一套 API。无论你是做语义搜索、RAG 召回还是多模态检索都可以在保持 OpenAI 生态兼容的前提下快速接入并通过批量处理与环境变量调优获得稳定高效的在线服务。【免费下载链接】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），仅供参考 Xinference 文本嵌入完全指南：Embeddings API、多引擎服务与多模态 WeMM 输入
Xinference 文本嵌入完全指南Embeddings API、多引擎服务与多模态 WeMM 输入【免费下载链接】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本文围绕 Xinference 的 Embeddings API 展开系统讲解文本嵌入的核心概念、OpenAI 兼容的/v1/embeddings接口、四种服务引擎sentence_transformers / vllm / flag / llama.cpp的选择依据、truncate_prompt_tokens截断机制以及 WeMM-Embedding 的多模态输入方式。读完本文你将掌握通过 cURL、OpenAI Python Client 和 Xinference Python Client 三种方式创建文本与多模态向量并能按检索、分类、聚类等场景正确配置引擎与参数。什么是文本嵌入Text Embeddings文本嵌入Text Embedding将一段文本映射为一个浮点数向量用于量化不同文本之间的语义相关程度。向量之间的距离是文本相似度的直接指标距离越小、相关性越高距离越大、相关性越低。这一能力支撑着搜索、聚类、推荐、异常检测、多样性测量与分类等一系列上层应用。在 Xinference 中嵌入模型通过 Embeddings API 对外提供服务。该 API 完全模仿 OpenAI 的 Create Embeddings 接口语义端点对应关系如下APIOpenAI 兼容端点Embeddings APIPOST /v1/embeddings在路由层面该端点由 xinference/api/routers/embeddings.py 注册到 FastAPI 路由表启用认证后要求models:read权限同一文件中还注册了POST /v1/convert_ids_to_tokens用于将 token id 序列解码回 token 文本便于调试分词结果。请求处理入口位于 xinference/api/restful_api.py服务端解析请求体中的model、input等字段将其余参数透传给底层模型实例的create_embedding并把返回的Embedding对象直接序列化为 JSON 响应。支持的模型Xinference 内置了一批开箱即用的嵌入模型涵盖常见中英文场景。全部内置嵌入模型清单可在文档 内置嵌入模型索引 中查看该索引由 embedding_index.rst.jinja 模板生成与模型描述文件同步维护。从源码结构看内置模型以EmbeddingModelFamilyV2的形式注册在 xinference/model/embedding/embed_family.py 的BUILTIN_EMBEDDING_MODELS与EMBEDDING_ENGINES两张注册表中每个模型家族声明了dimensions输出维度、max_tokens最大输入长度、language支持语言以及可选的额外模态能力model_abilityvision/video/audio其定义见 xinference/model/embedding/core.py。match_embedding会依据模型名、模型格式与量化方式完成匹配并支持从 ModelScope 下载当设置了download_hubmodelscope或环境变量启用 ModelScope 时优先选择 ModelScope 的 model spec。除内置模型外用户也可以在 Xinference 中注册自定义嵌入模型参见 自定义模型文档注册后同样进入上述匹配流程。选择服务引擎四种 embedding 引擎详解启动嵌入模型时通过model_engine参数命令行使用--model-engine指定服务引擎sentence_transformers默认引擎适用于全部嵌入模型。底层基于 Sentence-Transformers 框架加载 PyTorch 模型也是向后兼容性最好的选择。从 xinference/model/embedding/core.py 的实现可以看到当model_engine未指定时Xinference 会显式回退到sentence_transformers与 LLM 的默认行为不同这是嵌入模块特意保留的兼容策略。该引擎要求sentence-transformers3.1.0加载时默认对输出向量执行 L2 归一化normalize_embeddingsTrue便于下游直接使用点积代替余弦相似度相关实现见 xinference/model/embedding/sentence_transformers/core.py。vllm高吞吐服务引擎适用于名称以bge、gte、text2vec、m3e、Qwen3、WeMM、bce开头的模型家族例如bce-embedding-base_v1。模型前缀白名单定义于 xinference/model/embedding/vllm/core.py适合高并发在线检索场景。flag基于 FlagEmbedding 的引擎其核心价值在于支持混合检索hybrid retrieval可通过额外参数return_parseTrue同时获得稠密向量dense与稀疏向量sparse详见下文 FAQ 小节。llama.cpp服务于 GGUF 格式的嵌入模型对应LlamaCppEmbeddingSpecV1model_formatggufv2的模型规范。引擎与模型家族的匹配校验在 xinference/model/embedding/embed_family.py 的check_engine_by_model_name_and_engine及其虚拟环境版本中完成若目标模型不支持指定引擎启动时会直接抛出Model xxx cannot be run on engine xxx的明确报错。嵌入模型还支持通过 虚拟环境 隔离引擎依赖此时可通过virtualenv标记绕过引擎兼容性检查。控制输入长度truncate_prompt_tokens 截断机制Embeddings API 接受可选的truncate_prompt_tokens参数在编码前限制每个输入的 token 长度不设置 /null不进行截断正整数N将每个输入截断到至多N个 token-1截断到模型自身的最大输入长度即模型家族的max_tokens。使用示例curl -X POST \ http://XINFERENCE_HOST:XINFERENCE_PORT/v1/embeddings \ -H Content-Type: application/json \ -d { model: MODEL_UID, input: A very long document ..., truncate_prompt_tokens: 512 }截断的底层实现该参数的处理逻辑位于 xinference/model/embedding/core.py 的_truncate_sentences语义与 vLLM LLM 保持一致0封顶到 N 个 token0表示显式空输入max_length00则回退到模型自身的max_tokens当模型没有声明max_tokens时0会安全地放弃截断而非报错。截断是结构保持的_truncate_value见 xinference/model/embedding/core.py纯 token 数组List[int]/List[List[int]]按 token id 直接切片多模态字典Dict只截断其中的text字段image/video/audio等媒体字段原样保留——因为媒体字段可能是 URL、文件路径或 base64 载荷截断它们会直接损坏媒体数据普通字符串优先走 tokenizer 做 token 级截断_truncate_text若 tokenizer 调用失败如 llama.cpp 引擎没有 Python tokenizer则降级为字符级截断每 token 按约 4 个字符估算可通过环境变量XINFERENCE_EMBEDDING_TRUNCATE_CHAR_PER_TOKEN调整默认 4。该路径保证服务不会因截断失败而中断。该机制同时覆盖单条请求与批量请求create_embedding是extensible批处理方法批量模式下会先按 kwargs 哈希分组、再在组内统一截断最后按原始调用顺序还原index实现见 xinference/model/embedding/core.py。仓库中 test_truncate_prompt_tokens.py 对上述多种输入形态字符串、token 数组、多模态字典均有覆盖。内存占用控制为避免长文档批量编码引发显存 OOM嵌入模型在累计处理 token 数达到阈值时会主动清理缓存XINFERENCE_EMBEDDING_EMPTY_CACHE_COUNT默认 10 次调用或XINFERENCE_EMBEDDING_EMPTY_CACHE_TOKENS默认 8192 token任一条件满足即触发gc.collect()与显存释放见 xinference/model/embedding/core.py。多模态嵌入WeMM-Embedding 输入格式WeMM-Embedding 模型家族名称以WeMM-Embedding-开头接受文本、图像、视频、视觉文档以及交错多模态输入不支持音频。可用引擎为sentence_transformers默认与vllm。前者要求sentence-transformers5.7.0、transformers5.2.0与qwen-vl-utils0.0.14后者要求 vLLM 版本适配详见 xinference/model/embedding/sentence_transformers/core.py 与 xinference/model/embedding/vllm/core.py。输入形式一扁平字典一个扁平的输入字典可以包含任意有序组合的text、image与video字段。例如xinference launch \ --model-name WeMM-Embedding-2B \ --model-type embedding \ --model-engine sentence_transformers curl -X POST \ http://XINFERENCE_HOST:XINFERENCE_PORT/v1/embeddings \ -H Content-Type: application/json \ -d { model: MODEL_UID, input: { role: user, content: [ {type: image_url, image_url: {url: https://example.com/image.jpg}}, {type: text, text: Find content related to this image.}, {type: video_url, video_url: {url: https://example.com/video.mp4}} ] }, dimensions: 256 }输入形式二role / content 消息与交错排列若需要精确控制模态的排列顺序可传入role/content消息结构{role: user, content: [...]}其中content中的每一项为{type: image_url | video_url | text, ...}的字典image_url与video_url内容项同样被接受。此外也支持{messages: [...]}形式表达多轮消息会话。这些输入会被归一化为 WeMM 的对话消息格式归一化逻辑包括对音频输入的显式拒绝、对image_url/video_url的 URL 提取位于 xinference/model/embedding/wemm.py 的normalize_wemm_messages/normalize_wemm_inputs。注意本地媒体路径指向的是 Xinference 服务器上的文件。输出维度Matryoshka 维度选择请求中的dimensions参数用于选择模型支持的 Matryoshka嵌套向量维度之一。默认情况下Xinference 会对输出向量做维度截断并再次执行 L2 归一化在 sentence_transformers 引擎中dimensions会映射为底层truncate_dim见 xinference/model/embedding/sentence_transformers/core.py并对非法的 Matryoshka 维度抛出校验错误matryoshka_dimensions定义于模型 config在 vLLM 引擎中WeMM 嵌入通过池化参数与 chat template 实现见 xinference/model/embedding/vllm/core.py。视频输入方面当qwen-vl-utils的 torchvision 视频读取器不可用时Xinference 会自动安装 PyAV 回退读取器VIDEO_READER_BACKENDS[torchvision]替换见 xinference/model/embedding/wemm.py。快速上手三种方式调用 Embeddings API下面分别用 cURL、OpenAI Python Client 与 Xinference Python Client 创建文本向量。前提是已通过xinference launch启动一个嵌入模型并拿到它的模型 UIDMODEL_UID。方式一cURLcurl -X POST \ http://XINFERENCE_HOST:XINFERENCE_PORT/v1/embeddings \ -H accept: application/json \ -H Content-Type: application/json \ -d { model: MODEL_UID, input: What is the capital of China? }方式二OpenAI Python Client由于接口与 OpenAI 兼容只需将base_url指向 Xinference 的/v1即可无缝切换import openai client openai.Client( api_keycannot be empty, base_urlhttp://XINFERENCE_HOST:XINFERENCE_PORT/v1 ) client.embeddings.create( modelmodel_uid, input[What is the capital of China?] )方式三Xinference Python Client使用官方 Python 客户端xinference包时可以像调用本地模型一样操作from xinference.client import Client client Client(http://XINFERENCE_HOST:XINFERENCE_PORT) model client.get_model(MODEL_UID) input What is the capital of China? model.create_embedding(input)响应格式三种方式返回的 JSON 结构一致OpenAI 风格{ object: list, model: MODEL_UID, data: [{ index: 0, object: embedding, embedding: [ -0.014207549393177032, -0.01832585781812668, ... -0.03009396605193615, 0.05420297756791115] }], usage: { prompt_tokens: 37, total_tokens: 37 } }响应中的data[].embedding即为浮点向量usage.prompt_tokens统计本次输入消耗的 token 数。从源码实现看xinference/model/embedding/sentence_transformers/core.pytoken 统计通过对 batch 中attention_mask求和得到多模态输入如 CLIP、jina-embeddings-v4则统计input_ids/pixel_values的元素总数而 flag 引擎当前以prompt_tokens-1占位xinference/model/embedding/flag/core.pyvLLM 引擎与部分多模态路径的 token 统计也类似。批量传入多个字符串时data数组会按输入顺序返回对应数量的向量。进阶用法与 FAQ为什么 LLM 不提供 Embeddings API不提供。出于性能考虑Xinference 没有为 LLM 提供 embed 接口。嵌入任务应使用专门的嵌入模型而非通用 LLM。如何集成 LangChain可以。LangChain 官方文档提供了 Xinference 的 Text Embedding Models 集成章节LangChain 官方 Xinference 文档中的 Text Embedding Models: Xinference可直接参考其集成方式。Xinference 的 Embeddings API 与 OpenAI 兼容也可通过 LangChain 的 OpenAI Embeddings 封装快速接入。仓库内 xinference/model/embedding/core.py 的_fix_langchain_openai_inputs专门处理了 LangChain OpenAI 客户端可能传入的 token id 二维数组输入会先解码回字符串再编码保证集成路径下输入被正确理解。如何获取稀疏向量混合检索支持。使用flag引擎部署模型后调用 Embeddings API 时设置额外参数return_parseTrue对应源码中的return_sparse即可同时返回稀疏向量。此时响应的object为sparse_embeddingembedding字段为{token_id: weight}形式的稀疏字典见 xinference/model/embedding/flag/core.py可直接用于 BM25 风格的稀疏检索与稠密向量组成混合检索hybrid retrieval流水线。需要注意的是return_sparse仅受flag引擎支持若在sentence_transformers引擎下传入该参数会抛出 please use flag instead 的明确错误见 xinference/model/embedding/sentence_transformers/core.py。如何为 Jina 系列模型指定检索任务对于 jina-embeddings-v3/v4/v5 模型sentence_transformers 引擎会解析可选的task参数v3task映射为prompt_name如retrieval.query/retrieval.passagev4task直接透传给模型的forward()v5task透传给模型的encode()且当调用方未传task时默认回退到retrieval保证 OpenAI 风格的客户端无需感知该参数也能正常工作。任务白名单与别名映射定义于 xinference/model/embedding/sentence_transformers/core.py传入非法task会返回含合法取值列表的清晰报错。服务端处理长文档的性能建议结合上述机制服务超长文档时建议优先通过truncate_prompt_tokens在服务端统一截断避免每次请求都携带超长 payload批量请求由create_embedding的批处理路径自动按 kwargs 分组合并计算xinference/model/embedding/core.py多条相同参数的请求会合并为一次编码、显著提升吞吐同时注意XINFERENCE_EMBEDDING_EMPTY_CACHE_*环境变量对缓存清理频率的影响在显存紧张的设备上可适当调低阈值。总结Xinference 的 Embeddings API 以 OpenAI 兼容的/v1/embeddings端点统一了文本与多模态向量服务sentence_transformers作为默认引擎覆盖全部模型vllm面向高吞吐场景flag提供稀疏稠密混合检索能力llama.cpp服务 GGUF 模型truncate_prompt_tokens提供了从「不截断」到「封顶 N token」再到「模型上限」的完整控制并且对多模态输入做结构保持的文本字段截断WeMM-Embedding 家族进一步将图像、视频与文本交织输入纳入同一套 API。无论你是做语义搜索、RAG 召回还是多模态检索都可以在保持 OpenAI 生态兼容的前提下快速接入并通过批量处理与环境变量调优获得稳定高效的在线服务。【免费下载链接】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），仅供参考