企业官网建设流程全解析

Xinference 中部署与使用 bge-large-zh-v1.5 中文文本向量模型

【免费下载链接】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

bge-large-zh-v1.5 是 BAAI（北京智源人工智能研究院）推出的面向中文场景的文本向量（Embedding）模型，在 Xinference 中以内置模型形式开箱即用。本文以 doc/source/models/builtin/embedding/bge-large-zh-v1.5.rst 为核心，结合仓库中的模型规范、引擎实现与客户端代码，完整讲解该模型的规格参数、启动命令、引擎选型、API 调用方式与底层实现原理，帮助你快速搭建中文语义检索、RAG 知识库等应用。

一、模型规格总览

bge-large-zh-v1.5 在内置 Embedding 模型列表中属于中文专用模型，其核心规格如下表所示：

在 Xinference 中，内置模型的元信息统一维护在 xinference/model/embedding/model_spec.json（第 456–497 行）。该模型对应的条目还包含以下补充细节：

• 模型格式（model_format）：pytorch，即原生 PyTorch 权重，无量化变体（quantizations仅含"none"）；
• 固定版本号（model_revision）：Hugging Face 侧锁定为029c4bfff6b0c5cfcd20b40c17ed52ec55202748，ModelScope 侧为v0.0.1，确保每次启动拉取的都是可复现的同一份权重；
• 虚拟环境依赖：virtualenv.packages字段声明了不同引擎所需的依赖，例如#sentence_transformers_dependencies#、#system_torch#、#system_torchvision#用于 sentence_transformers 引擎，FlagEmbedding用于 flag 引擎，#vllm_dependencies#、#system_numpy#用于 vllm 引擎。

这些元数据在 Xinference 启动时通过_install()注册流程加载进BUILTIN_EMBEDDING_MODELS注册表（参见 xinference/model/embedding/init.py），供后续匹配引擎与下发启动任务使用。

二、启动模型

2.1 命令行启动

内置模型只需一条命令即可启动：

xinference launch --model-name bge-large-zh-v1.5 --model-type embedding

其中：

• --model-name：指定内置模型名，这里为bge-large-zh-v1.5；
• --model-type：指定模型类型，Embedding 模型必须显式声明为embedding（默认值是 LLM）。

根据 xinference/deploy/cmdline.py 中 launch 命令的参数定义，还可以补充以下常用选项：

• --model-engine / -en：指定推理引擎（见下文第三节），不传时系统会自动选择；
• --model-format / -f：指定模型格式，本模型固定为pytorch，一般无需填写；
• --model-uid：自定义模型唯一标识，便于后续 API 调用时引用；
• --device：指定运行设备（如cuda、cpu）；
• --n-gpu：使用的 GPU 数量；
• --download-hub：指定从huggingface还是modelscope下载权重。

提示：在中国大陆网络环境下，可通过--download-hub modelscope从 ModelScope 拉取权重以提升下载速度；若未显式指定，Xinference 会依据环境判断默认下载源（参见 xinference/model/embedding/embed_family.py 中match_embedding对download_hub的处理）。

2.2 查看可用内置模型

启动前可以通过注册表命令确认该模型已被识别：

xinference registrations -t embedding

输出将列出全部内置 Embedding 模型，其中包含bge-large-zh-v1.5及其语言、向量维度、是否内置等信息（该命令的展示逻辑同样位于 xinference/deploy/cmdline.py）。

三、推理引擎选择与底层实现

bge-large-zh-v1.5 为pytorch格式，Xinference 的 Embedding 模块在 xinference/model/embedding/init.py 中注册了四类引擎：

在 xinference/model/embedding/core.py 的create_embedding_model_instance中可以看到：当调用方未显式指定引擎时，所有内置 Embedding 模型默认使用sentence_transformers；随后通过match_embedding匹配模型族、再由check_engine_by_model_name_and_engine（或开启虚拟环境时的..._with_virtual_env变体）解析出具体的引擎实现类并完成实例化。

如果希望显式使用某类引擎，可以这样启动：

xinference launch --model-name bge-large-zh-v1.5 --model-type embedding --model-engine flag

3.1 sentence_transformers 引擎

该引擎由SentenceTransformerEmbeddingModel实现（xinference/model/embedding/sentence_transformers/core.py），加载时通过SentenceTransformer读取本地缓存的权重目录。其_create_embedding流程与官方 sentence-transformers 对齐：

• 按文本长度降序排序、分 batch（默认batch_size=32）编码，避免长文本集中造成显存波动；
• 默认开启normalize_embeddings=True，输出的 1024 维向量会被 L2 归一化，可直接用点积替代余弦相似度进行检索排序；
• 通过truncate_dim支持输出维度截断（本模型无 Matryoshka 能力，保持 1024 维）；
• 每次调用会累加attention_mask统计真实 token 数，写入响应的usage字段。

3.2 flag 引擎

若选择 flag 引擎，则由FlagEmbeddingModel（xinference/model/embedding/flag/core.py）驱动，底层使用BGEM3FlagModel加载模型：

• 支持torch_dtype参数指定float16/float32/bfloat16，其中 fp16 会映射为use_fp16=True；
• 支持return_sparse参数返回稀疏向量（lexical_weights），为 BM25 式检索提供补充信号；
• 注意：flag 引擎当前不支持dimensions参数（源码中会直接抛出NotImplementedError）。

四、通过客户端与 OpenAI 兼容 API 调用

4.1 使用 Xinference Python Client

启动后，可通过 Python Client 加载模型句柄并生成向量：

from xinference.client import Client client = Client("http://localhost:9997") # 启动模型（embedding 模型必须显式指定 model_type） model_uid = client.launch_model( model_name="bge-large-zh-v1.5", model_type="embedding" ) model = client.get_model(model_uid) input_text = "什么是知识蒸馏？" result = model.create_embedding(input_text) # result["data"][0]["embedding"] 即为 1024 维向量

RESTfulEmbeddingModelHandle.create_embedding（xinference/client/restful/restful_client.py）与异步版（xinference/client/restful/async_restful_client.py）均封装了对POST /v1/embeddings的请求，请求体结构为{"model": model_uid, "input": ...}，与 OpenAI Embeddings 接口保持一致。也支持一次传入多条文本（List[str]）进行批量向量化。

4.2 使用 OpenAI SDK

由于 Xinference 提供 OpenAI 兼容接口，任何支持 OpenAI Embeddings API 的客户端都可以直接复用：

from openai import OpenAI # api_key 不能为空，任意字符串即可 client = OpenAI(api_key="not empty", base_url="http://localhost:9997/v1") resp = client.embeddings.create( model=model_uid, input=["什么是知识蒸馏？", "向量检索如何工作？"] ) for item in resp.data: print(len(item.embedding)) # 1024

4.3 关于输入截断

Embedding 模型的max_tokens=512意味着超出上限的输入会被截断。Xinference 在 xinference/model/embedding/core.py 的create_embedding入口支持truncate_prompt_tokens参数，语义与 vLLM LLM 保持一致：

• None：不截断；
• 正整数：截断到指定 token 数；
• 0：显式空输入；
• 负值：按模型自身max_tokens（即 512）截断。

截断基于 tokenizer 实现（优先以模型 tokenizer 分 token 后截断，异常时回退到按字符数粗切），并且能保持多模态 dict 输入的结构完整性。批量请求时还会先按参数哈希分组、再合并编码，最后按原始调用顺序切分返回，保证批处理场景下每个调用方拿到的index从 0 起正确编号。

五、资源管理与缓存

针对 Embedding 服务的长时运行场景，Xinference 在基类中内置了显存缓存清理机制（xinference/model/embedding/core.py）：

• 默认每处理 10 次调用（EMBEDDING_EMPTY_CACHE_COUNT）触发一次gc.collect()与显存释放；
• 或当单批累计 token 数达到 8192（EMBEDDING_EMPTY_CACHE_TOKENS）时提前触发；
• 两个阈值均支持通过环境变量XINFERENCE_EMBEDDING_EMPTY_CACHE_COUNT、XINFERENCE_EMBEDDING_EMPTY_CACHE_TOKENS调整。

此外，模型权重首次启动时会下载到本地缓存目录（由EmbeddingCacheManager管理，见 xinference/model/embedding/cache_manager.py），后续启动直接复用本地副本，无需重复下载。

六、典型应用场景

bge-large-zh-v1.5 输出 1024 维、已 L2 归一化的中文语义向量，可直接落地以下场景：

1. RAG / 知识库问答：将文档切片批量向量化存入向量数据库，查询时对 query 编码后做向量相似度检索；
2. 语义搜索 / 相似文本匹配：利用点积或余弦相似度对候选文本排序；
3. 文本聚类与分类：将文本向量作为下游 ML 模型的特征输入。

结合 Xinference 的 OpenAI 兼容接口，这些能力可以无缝接入 LangChain、LlamaIndex 等生态，与同服务内的 LLM 模型配合形成完整的"向量召回 + 生成"链路。

七、参考资源

• 模型文档：doc/source/models/builtin/embedding/bge-large-zh-v1.5.rst
• 内置模型注册表：doc/source/models/builtin/embedding/index.rst
• 模型元信息：xinference/model/embedding/model_spec.json
• 引擎注册与匹配：xinference/model/embedding/init.py、xinference/model/embedding/embed_family.py
• 模型基类实现：xinference/model/embedding/core.py
• sentence_transformers 引擎：xinference/model/embedding/sentence_transformers/core.py
• flag 引擎：xinference/model/embedding/flag/core.py
• 客户端 API 示例：doc/source/user_guide/client_api.rst

【免费下载链接】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