尧图网页设计 
Xinference 自定义模型完全指南从 model_path 直启到注册、管理与调用【免费下载链接】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/inferenceXinference 提供了一套灵活且完整的自定义模型集成方案让开发者能够把本地权重、Hugging Face/ModelScope 模型甚至私有镜像中的模型统一接入其生产级推理 API。本文以仓库文档 doc/source/models/custom.rst 为主体结合 xinference/model/custom.py、xinference/client/restful/restful_client.py 等源码实现完整讲解「免注册直启模型」「定义自定义模型」「注册 / 列表 / 启动 / 调用 / 注销」五种实操路径帮助你用一条命令或一次注册把任意模型纳入 Xinference 统一管理。一、两条路线概览直接启动 vs 注册模型在 Xinference 中接入一个现有模型有两条路线适用场景不同路线适用前提操作成本典型场景直接启动model_path模型所属的model_family必须在内置支持列表内无需注册一次调用即可快速验证已下载的官方权重临时跑一个模型注册自定义模型模型家族不在内置列表或需要长期复用、团队共享需要编写一份 JSON 定义并注册私有微调模型、本地专用模型、跨机器分发两条路线的最终落点一致注册后的模型也会像内置模型一样出现在启动接口中被 xinference/model/custom.py 中的ModelRegistry统一管理。二、路线一用 model_path 直接启动已存在的模型从v0.14.0起Xinference 支持在启动接口中直接传入model_path来加载一个已存在的模型文件免去下载和注册步骤。前提是该模型的model_family必须属于内置支持列表如qwen1.5-chat否则仍需走注册流程。2.1 CLI 启动xinference launch --model-path model_file_path --model-engine engine -n qwen1.5-chat参数说明--model-path模型文件路径。GGUF 格式必须指向具体文件PyTorch 等格式指向模型目录与model_uri的语义一致。--model-engine指定推理引擎如transformers、vllm、llama.cpp等取决于模型格式与后端支持。-n内置模型家族名称如qwen1.5-chat。注意CLI 推荐使用 kebab-case 的--model-path--model_path下划线是历史兼容写法不推荐使用。2.2 REST API 启动curl -X POST \ http://127.0.0.1:9997/v1/models \ -H accept: application/json \ -H Content-Type: application/json \ -d { model_engine: engine, model_name: qwen1.5-chat, model_path: model_file_path }2.3 Python 客户端启动from xinference.client import RESTfulClient client RESTfulClient(http://127.0.0.1:9997) model_uid client.launch_model( model_engineinference_engine, model_nameqwen1.5-chat, model_pathmodel_file_path ) print(Model uid: model_uid)上面的示例演示了在不注册模型的情况下直接启动一个qwen1.5-chat模型文件。2.4 分布式场景在分布式部署中如果模型文件位于某个特定 worker 上只需在启动接口中同时指定worker_ip与model_pathXinference 就会在该 worker 上直接加载无需把权重拷贝到所有节点。这一能力对应 restful_client.py 中launch_model的worker_ip、model_path参数其中model_path的语义为「GGUF 格式传文件路径其余格式传模型目录」。三、路线二前置定义自定义模型 JSON当模型家族不在内置列表时需要先编写一份 JSON 定义。自v2.0.0起注册 LLM 还可以走 Web UI 的「自动配置解析」来减少手写工作量。3.1 Web UI 自动解析v2.0.0在 Web UI 注册自定义 LLM 时Xinference 可以自动解析模型配置并预填关键字段。你只需提供Model path / Model ID模型所在位置本地路径或 Hub ID 均可Model Family模型家族名。解析完成后UI 会自动填充Context Length、Model_Languages、Model_Abilities、Model_Specs等字段。保存前你可以逐一审阅和修改这些自动生成的值确保与实际模型一致。3.2 LLM 模板{ version: 2, context_length: 32768, model_name: custom-qwen-2.5, model_lang: [ en, zh ], model_ability: [ generate ], model_description: This is a custom model description., model_family: my-custom-qwen-2.5, model_specs: [ { model_format: pytorch, model_size_in_billions: 0_5, quantization: none, model_id: null, model_hub: huggingface, model_uri: file:///path/to/models--Qwen--Qwen2.5-0.5B, model_revision: null, activated_size_in_billions: null } ], chat_template: null, stop_token_ids: null, stop: null, reasoning_start_tag: null, reasoning_end_tag: null, cache_config: null, virtualenv: { packages: [], inherit_pip_config: true, index_url: null, extra_index_url: null, find_links: null, trusted_host: null, no_build_isolation: null }, is_builtin: false }要点解读model_ability中的能力词可取值包括embed、generate、chat等本示例仅声明generate若model_ability包含chat则必须配置chat_templateJinja 模板字符串通常可在模型目录的tokenizer_config.json中找到否则聊天时无法生成正确的完整 promptmodel_size_in_billions写成字符串0_5表示 0.5B这是模型规格命名中常见的转义写法。3.3 Embedding 模板{ version: 2, model_name: my-bge-large-zh-v1.5, dimensions: 1024, max_tokens: 512, language: [ zh ], model_specs: [ { model_format: pytorch, model_hub: huggingface, model_id: null, model_uri: file:///path/to/my-bge-large-zh-v1.5, model_revision: null, quantization: none } ], cache_config: null, virtualenv: { packages: [], inherit_pip_config: true, index_url: null, extra_index_url: null, find_links: null, trusted_host: null, no_build_isolation: null }, is_builtin: false }3.4 Rerank 模板{ version: 2, model_name: my-bge-reranker-base, model_specs: [ { model_format: pytorch, model_hub: huggingface, model_id: null, model_revision: null, model_uri: file:///path/to/my-bge-reranker-base, quantization: none } ], language: [ en, zh ], type: unknown, max_tokens: 512, virtualenv: { packages: [], inherit_pip_config: true, index_url: null, extra_index_url: null, find_links: null, trusted_host: null, no_build_isolation: null }, is_builtin: false }3.5 Image 模板{ model_name: my-qwen-image, model_id: null, model_revision: null, model_hub: huggingface, cache_config: null, version: 2, model_family: stable_diffusion, model_ability: null, controlnet: [], default_model_config: {}, default_generate_config: {}, gguf_model_id: null, gguf_quantizations: null, gguf_model_file_name_template: null, lightning_model_id: null, lightning_versions: null, lightning_model_file_name_template: null, virtualenv: { packages: [], inherit_pip_config: true, index_url: null, extra_index_url: null, find_links: null, trusted_host: null, no_build_isolation: null }, model_uri: file:///path/to/my-qwen-image, is_builtin: false }3.6 Audio 模板{ model_name: my-ChatTTS, model_id: null, model_revision: null, model_hub: huggingface, cache_config: null, version: 2, model_family: ChatTTS, multilingual: false, language: null, model_ability: [ text2audio ], default_model_config: null, default_transcription_config: null, engine: null, virtualenv: { packages: [], inherit_pip_config: true, index_url: null, extra_index_url: null, find_links: null, trusted_host: null, no_build_isolation: null }, model_uri: file:///path/to/my-ChatTTS, is_builtin: false }3.7 Flexible 模板flexible类型用于无法归入上述任何类别的任意模型通过「启动器launcher」与参数来驱动例如 xinference/model/flexible/launchers/transformers_launcher.py 对应 transformers 启动器{ model_name: my-flexible-model, model_id: null, model_revision: null, model_hub: huggingface, cache_config: null, version: 2, model_description: This is a model description., model_uri: file:///path/to/my-flexible-model, launcher: xinference.model.flexible.launchers.transformers, launcher_args: {}, virtualenv: { packages: [], inherit_pip_config: true, index_url: null, extra_index_url: null, find_links: null, trusted_host: null, no_build_isolation: null }, is_builtin: false }仓库中 xinference/model/flexible/launchers 目录还提供了modelscope_launcher.py、yolo_launcher.py、image_process_launcher.py等更多启动器可根据模型类型选择launcher路径并通过launcher_args传入 JSON 字符串形式的启动参数。四、核心字段详解以下字段对注册结果有决定性影响逐一说明model_name必填模型名称字符串。必须以字母或数字开头只能包含字母、数字、下划线和连字符。注册时 xinference/model/utils.py 中的is_valid_model_name会校验命名合法性且不能与已注册模型或内置模型重名否则 xinference/model/custom.py 的register会抛出ValueError。context_length可选LLM模型训练时支持的最大上下文长度输入 输出。不定义时默认 2048 tokens约 1500 词。dimensions必填EmbeddingEmbedding 模型输出向量的维度。max_tokensEmbedding/Rerank单次请求中 Embedding 模型可处理的最大输入 token 数。model_langLLM/Embedding/Rerank支持语言列表如[en]表示支持英文。model_abilityLLM能力列表可包含embed、generate、chat等取值。model_family必填模型家族名称不得与任何内置模型名冲突。model_specs模型规格对象数组包含model_format模型格式如pytorch、ggufv2model_size_in_billions参数量十亿quantization可用量化列表。PyTorch 模型可取4-bit、8-bit、noneGGUFv2 模型需与model_file_name_template对应部分引擎还支持fp4/fp8/bnb格式后端支持情况参见 doc/source/getting_started/installation.rstmodel_id模型 ID通常是 Hugging Face 仓库标识。如果未提供model_uriXinference 会尝试从该 ID 对应的 Hugging Face 仓库下载模型model_hub下载来源如huggingface、modelscopemodel_uri模型加载 URI如file:///path/to/llama-2-7b。GGUFv2 格式必须是具体文件路径PyTorch 格式必须是模型文件所在目录。缺省时 Xinference 会尝试按model_id从 Hugging Face 下载。注册时is_valid_model_uri见 xinference/model/utils.py会校验file://路径必须是绝对路径且实际存在model_revision仓库中要使用的具体版本或 commit hash。chat_template若model_ability包含chat则必填Jinja 模板字符串通常可从模型目录的tokenizer_config.json提取。stop_token_idschat 能力整数列表控制模型停止生成通常可从generation_config.json或tokenizer_config.json提取。stopchat 能力字符串列表作用同上。reasoning_start_tag / reasoning_end_tag用于显式引导 LLM 开始/结束思维链chain-of-thought推理输出的特殊 token 或 prompt。cache_config系统存储与管理临时数据缓存的参数与规则字符串。virtualenv模型依赖隔离配置对象细节参见 doc/source/models/virtualenv.rst。补充model_uri支持 OCI 镜像格式除file://之外model_uri还接受oci://registry/repository:tag用于加载发布为 CNCF ModelPack 制品容器镜像的模型。拉取这类模型需要一个正在运行的llmman守护进程llmman serve且llmman二进制位于PATH中可通过LLMMAN_HOST指定远端守护进程或用XINFERENCE_LLMMAN_BIN指向PATH之外的二进制。对应实现见 xinference/model/llmman.py 与 xinference/model/oci_utils.py。五、注册自定义模型5.1 Python 方式import json from xinference.client import Client with open(model.json) as fd: model fd.read() # replace with real xinference endpoint endpoint http://localhost:9997 client Client(endpoint) client.register_model(model_typemodel_type, modelmodel, persistFalse)5.2 CLI 方式xinference register --model-type model_type --file model.json --persistmodel_type在上述命令中替换为LLM、embedding或rerank下文同。persist决定注册是否落盘持久化不持久化的注册在服务重启后失效持久化注册会经由 xinference/model/cache_manager.py 的CacheManager写入自定义模型存储。5.3 注册背后的实现注册最终走到 xinference/model/custom.py 的ModelRegistry.register流程为校验model_name合法性is_valid_model_name校验model_uri合法性check_model_uri→is_valid_model_uri加锁检查与内置模型、已有自定义模型是否重名冲突即抛ValueError: Model name conflicts with existing model ...追加到自定义模型列表若persistTrue写入持久化存储。不同模型类型对应不同注册表由 xinference/model/custom.py 的RegistryManager.get_registry按类型分发LLM、embedding、rerank、image、audio、flexible。其中 LLM 注册表xinference/model/llm/custom.py在add_ud_model时会额外调用generate_engine_config_by_model_family为模型生成引擎配置注销时会同步删除LLM_ENGINES中的对应条目避免残留脏配置。六、列出内置与自定义模型registrations client.list_model_registrations(model_typemodel_type)或通过 CLIxinference registrations --model-type model_typelist_model_registrations见 restful_client.py请求/v1/model_registrations/{model_type}接口detailedTrue时可返回更详细的规格信息。七、启动自定义模型uid client.launch_model(model_namecustom-llama-2, model_formatpytorch)或通过 CLIxinference launch --model-name custom-llama-2 --model-format pytorch启动成功后返回模型 UIDmodel_uid。从源码看restful_client.pylaunch_model支持model_type、model_engine、model_size_in_billions、quantization、replica、n_worker、n_gpu默认autoNone表示纯 CPU、worker_ip、gpu_idx、model_path、enable_virtual_env等丰富参数可灵活适配单机与分布式部署。八、与自定义模型交互model client.get_model(model_uiduid) model.generate(What is the largest animal in the world?)返回结果示例OpenAI 兼容格式{ id:cmpl-a4a9d9fc-7703-4a44-82af-fce9e3c0e52a, object:text_completion, created:1692024624, model:43e1f69a-3ab0-11ee-8f69-fa163e74fa2d, choices:[ { text:\nWhat does an octopus look like?\nHow many human hours has an octopus been watching you for?, index:0, logprobs:None, finish_reason:stop } ], usage:{ prompt_tokens:10, completion_tokens:23, total_tokens:33 } }或通过 CLI将${UID}替换为真实模型 UIDxinference generate --model-uid ${UID}自定义模型启动后走的是与内置模型完全一致的统一推理 API客户端无需关心模型是内置还是自定义这正是「Swap GPT for any LLM by changing a single line of code」的基础。九、注销自定义模型model client.unregister_model(model_typemodel_type, model_namecustom-llama-2)或通过 CLIxinference unregister --model-type model_type --model-name custom-llama-2从 xinference/model/custom.py 的实现看unregister会先从内存注册表移除模型再调用remove_ud_model_files清理持久化文件若模型不存在默认抛ValueError: Model not found。注销后该模型即无法再被启动需重新注册才能使用。十、实践建议与注意事项优先复用内置家族能直接用model_path直启的模型不要注册成本最低注册仅用于内置列表之外的模型。model_uri三选一本地文件file://绝对路径、Hub ID配合model_id/model_hub自动下载、OCI 镜像oci:// llmman。三者是互斥的加载来源。chat 能力必配 chat_template忘记配置chat_template会导致带chat能力的模型无法正确构造 prompt。命名规范model_name只能含字母、数字、下划线和连字符且不能与内置/已注册模型重名否则注册直接失败。持久化与否要想清楚--persist仅适用于需要跨重启保留的场景临时调试建议不持久化避免污染模型目录。虚拟环境隔离依赖特殊的模型如需要特定版 vLLM/transformers可启用virtualenv配置按模型隔离依赖详见 doc/source/models/virtualenv.rst。结语从v0.14.0的model_path直启到v2.0.0的 Web UI 自动解析再到覆盖 LLM / Embedding / Rerank / Image / Audio / Flexible 六类模型的注册体系Xinference 的自定义模型能力已经形成「直启 → 定义 → 注册 → 管理 → 调用 → 注销」的完整闭环。配合 xinference/model/custom.py 中统一的注册表设计与 xinference/client/restful/restful_client.py 中统一的 REST 接口无论模型来自本地、Hub 还是容器镜像都可以用同一套 API 无缝接入生产推理环境。【免费下载链接】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 自定义模型完全指南：从 model_path 直启到注册、管理与调用
Xinference 自定义模型完全指南从 model_path 直启到注册、管理与调用【免费下载链接】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/inferenceXinference 提供了一套灵活且完整的自定义模型集成方案让开发者能够把本地权重、Hugging Face/ModelScope 模型甚至私有镜像中的模型统一接入其生产级推理 API。本文以仓库文档 doc/source/models/custom.rst 为主体结合 xinference/model/custom.py、xinference/client/restful/restful_client.py 等源码实现完整讲解「免注册直启模型」「定义自定义模型」「注册 / 列表 / 启动 / 调用 / 注销」五种实操路径帮助你用一条命令或一次注册把任意模型纳入 Xinference 统一管理。一、两条路线概览直接启动 vs 注册模型在 Xinference 中接入一个现有模型有两条路线适用场景不同路线适用前提操作成本典型场景直接启动model_path模型所属的model_family必须在内置支持列表内无需注册一次调用即可快速验证已下载的官方权重临时跑一个模型注册自定义模型模型家族不在内置列表或需要长期复用、团队共享需要编写一份 JSON 定义并注册私有微调模型、本地专用模型、跨机器分发两条路线的最终落点一致注册后的模型也会像内置模型一样出现在启动接口中被 xinference/model/custom.py 中的ModelRegistry统一管理。二、路线一用 model_path 直接启动已存在的模型从v0.14.0起Xinference 支持在启动接口中直接传入model_path来加载一个已存在的模型文件免去下载和注册步骤。前提是该模型的model_family必须属于内置支持列表如qwen1.5-chat否则仍需走注册流程。2.1 CLI 启动xinference launch --model-path model_file_path --model-engine engine -n qwen1.5-chat参数说明--model-path模型文件路径。GGUF 格式必须指向具体文件PyTorch 等格式指向模型目录与model_uri的语义一致。--model-engine指定推理引擎如transformers、vllm、llama.cpp等取决于模型格式与后端支持。-n内置模型家族名称如qwen1.5-chat。注意CLI 推荐使用 kebab-case 的--model-path--model_path下划线是历史兼容写法不推荐使用。2.2 REST API 启动curl -X POST \ http://127.0.0.1:9997/v1/models \ -H accept: application/json \ -H Content-Type: application/json \ -d { model_engine: engine, model_name: qwen1.5-chat, model_path: model_file_path }2.3 Python 客户端启动from xinference.client import RESTfulClient client RESTfulClient(http://127.0.0.1:9997) model_uid client.launch_model( model_engineinference_engine, model_nameqwen1.5-chat, model_pathmodel_file_path ) print(Model uid: model_uid)上面的示例演示了在不注册模型的情况下直接启动一个qwen1.5-chat模型文件。2.4 分布式场景在分布式部署中如果模型文件位于某个特定 worker 上只需在启动接口中同时指定worker_ip与model_pathXinference 就会在该 worker 上直接加载无需把权重拷贝到所有节点。这一能力对应 restful_client.py 中launch_model的worker_ip、model_path参数其中model_path的语义为「GGUF 格式传文件路径其余格式传模型目录」。三、路线二前置定义自定义模型 JSON当模型家族不在内置列表时需要先编写一份 JSON 定义。自v2.0.0起注册 LLM 还可以走 Web UI 的「自动配置解析」来减少手写工作量。3.1 Web UI 自动解析v2.0.0在 Web UI 注册自定义 LLM 时Xinference 可以自动解析模型配置并预填关键字段。你只需提供Model path / Model ID模型所在位置本地路径或 Hub ID 均可Model Family模型家族名。解析完成后UI 会自动填充Context Length、Model_Languages、Model_Abilities、Model_Specs等字段。保存前你可以逐一审阅和修改这些自动生成的值确保与实际模型一致。3.2 LLM 模板{ version: 2, context_length: 32768, model_name: custom-qwen-2.5, model_lang: [ en, zh ], model_ability: [ generate ], model_description: This is a custom model description., model_family: my-custom-qwen-2.5, model_specs: [ { model_format: pytorch, model_size_in_billions: 0_5, quantization: none, model_id: null, model_hub: huggingface, model_uri: file:///path/to/models--Qwen--Qwen2.5-0.5B, model_revision: null, activated_size_in_billions: null } ], chat_template: null, stop_token_ids: null, stop: null, reasoning_start_tag: null, reasoning_end_tag: null, cache_config: null, virtualenv: { packages: [], inherit_pip_config: true, index_url: null, extra_index_url: null, find_links: null, trusted_host: null, no_build_isolation: null }, is_builtin: false }要点解读model_ability中的能力词可取值包括embed、generate、chat等本示例仅声明generate若model_ability包含chat则必须配置chat_templateJinja 模板字符串通常可在模型目录的tokenizer_config.json中找到否则聊天时无法生成正确的完整 promptmodel_size_in_billions写成字符串0_5表示 0.5B这是模型规格命名中常见的转义写法。3.3 Embedding 模板{ version: 2, model_name: my-bge-large-zh-v1.5, dimensions: 1024, max_tokens: 512, language: [ zh ], model_specs: [ { model_format: pytorch, model_hub: huggingface, model_id: null, model_uri: file:///path/to/my-bge-large-zh-v1.5, model_revision: null, quantization: none } ], cache_config: null, virtualenv: { packages: [], inherit_pip_config: true, index_url: null, extra_index_url: null, find_links: null, trusted_host: null, no_build_isolation: null }, is_builtin: false }3.4 Rerank 模板{ version: 2, model_name: my-bge-reranker-base, model_specs: [ { model_format: pytorch, model_hub: huggingface, model_id: null, model_revision: null, model_uri: file:///path/to/my-bge-reranker-base, quantization: none } ], language: [ en, zh ], type: unknown, max_tokens: 512, virtualenv: { packages: [], inherit_pip_config: true, index_url: null, extra_index_url: null, find_links: null, trusted_host: null, no_build_isolation: null }, is_builtin: false }3.5 Image 模板{ model_name: my-qwen-image, model_id: null, model_revision: null, model_hub: huggingface, cache_config: null, version: 2, model_family: stable_diffusion, model_ability: null, controlnet: [], default_model_config: {}, default_generate_config: {}, gguf_model_id: null, gguf_quantizations: null, gguf_model_file_name_template: null, lightning_model_id: null, lightning_versions: null, lightning_model_file_name_template: null, virtualenv: { packages: [], inherit_pip_config: true, index_url: null, extra_index_url: null, find_links: null, trusted_host: null, no_build_isolation: null }, model_uri: file:///path/to/my-qwen-image, is_builtin: false }3.6 Audio 模板{ model_name: my-ChatTTS, model_id: null, model_revision: null, model_hub: huggingface, cache_config: null, version: 2, model_family: ChatTTS, multilingual: false, language: null, model_ability: [ text2audio ], default_model_config: null, default_transcription_config: null, engine: null, virtualenv: { packages: [], inherit_pip_config: true, index_url: null, extra_index_url: null, find_links: null, trusted_host: null, no_build_isolation: null }, model_uri: file:///path/to/my-ChatTTS, is_builtin: false }3.7 Flexible 模板flexible类型用于无法归入上述任何类别的任意模型通过「启动器launcher」与参数来驱动例如 xinference/model/flexible/launchers/transformers_launcher.py 对应 transformers 启动器{ model_name: my-flexible-model, model_id: null, model_revision: null, model_hub: huggingface, cache_config: null, version: 2, model_description: This is a model description., model_uri: file:///path/to/my-flexible-model, launcher: xinference.model.flexible.launchers.transformers, launcher_args: {}, virtualenv: { packages: [], inherit_pip_config: true, index_url: null, extra_index_url: null, find_links: null, trusted_host: null, no_build_isolation: null }, is_builtin: false }仓库中 xinference/model/flexible/launchers 目录还提供了modelscope_launcher.py、yolo_launcher.py、image_process_launcher.py等更多启动器可根据模型类型选择launcher路径并通过launcher_args传入 JSON 字符串形式的启动参数。四、核心字段详解以下字段对注册结果有决定性影响逐一说明model_name必填模型名称字符串。必须以字母或数字开头只能包含字母、数字、下划线和连字符。注册时 xinference/model/utils.py 中的is_valid_model_name会校验命名合法性且不能与已注册模型或内置模型重名否则 xinference/model/custom.py 的register会抛出ValueError。context_length可选LLM模型训练时支持的最大上下文长度输入 输出。不定义时默认 2048 tokens约 1500 词。dimensions必填EmbeddingEmbedding 模型输出向量的维度。max_tokensEmbedding/Rerank单次请求中 Embedding 模型可处理的最大输入 token 数。model_langLLM/Embedding/Rerank支持语言列表如[en]表示支持英文。model_abilityLLM能力列表可包含embed、generate、chat等取值。model_family必填模型家族名称不得与任何内置模型名冲突。model_specs模型规格对象数组包含model_format模型格式如pytorch、ggufv2model_size_in_billions参数量十亿quantization可用量化列表。PyTorch 模型可取4-bit、8-bit、noneGGUFv2 模型需与model_file_name_template对应部分引擎还支持fp4/fp8/bnb格式后端支持情况参见 doc/source/getting_started/installation.rstmodel_id模型 ID通常是 Hugging Face 仓库标识。如果未提供model_uriXinference 会尝试从该 ID 对应的 Hugging Face 仓库下载模型model_hub下载来源如huggingface、modelscopemodel_uri模型加载 URI如file:///path/to/llama-2-7b。GGUFv2 格式必须是具体文件路径PyTorch 格式必须是模型文件所在目录。缺省时 Xinference 会尝试按model_id从 Hugging Face 下载。注册时is_valid_model_uri见 xinference/model/utils.py会校验file://路径必须是绝对路径且实际存在model_revision仓库中要使用的具体版本或 commit hash。chat_template若model_ability包含chat则必填Jinja 模板字符串通常可从模型目录的tokenizer_config.json提取。stop_token_idschat 能力整数列表控制模型停止生成通常可从generation_config.json或tokenizer_config.json提取。stopchat 能力字符串列表作用同上。reasoning_start_tag / reasoning_end_tag用于显式引导 LLM 开始/结束思维链chain-of-thought推理输出的特殊 token 或 prompt。cache_config系统存储与管理临时数据缓存的参数与规则字符串。virtualenv模型依赖隔离配置对象细节参见 doc/source/models/virtualenv.rst。补充model_uri支持 OCI 镜像格式除file://之外model_uri还接受oci://registry/repository:tag用于加载发布为 CNCF ModelPack 制品容器镜像的模型。拉取这类模型需要一个正在运行的llmman守护进程llmman serve且llmman二进制位于PATH中可通过LLMMAN_HOST指定远端守护进程或用XINFERENCE_LLMMAN_BIN指向PATH之外的二进制。对应实现见 xinference/model/llmman.py 与 xinference/model/oci_utils.py。五、注册自定义模型5.1 Python 方式import json from xinference.client import Client with open(model.json) as fd: model fd.read() # replace with real xinference endpoint endpoint http://localhost:9997 client Client(endpoint) client.register_model(model_typemodel_type, modelmodel, persistFalse)5.2 CLI 方式xinference register --model-type model_type --file model.json --persistmodel_type在上述命令中替换为LLM、embedding或rerank下文同。persist决定注册是否落盘持久化不持久化的注册在服务重启后失效持久化注册会经由 xinference/model/cache_manager.py 的CacheManager写入自定义模型存储。5.3 注册背后的实现注册最终走到 xinference/model/custom.py 的ModelRegistry.register流程为校验model_name合法性is_valid_model_name校验model_uri合法性check_model_uri→is_valid_model_uri加锁检查与内置模型、已有自定义模型是否重名冲突即抛ValueError: Model name conflicts with existing model ...追加到自定义模型列表若persistTrue写入持久化存储。不同模型类型对应不同注册表由 xinference/model/custom.py 的RegistryManager.get_registry按类型分发LLM、embedding、rerank、image、audio、flexible。其中 LLM 注册表xinference/model/llm/custom.py在add_ud_model时会额外调用generate_engine_config_by_model_family为模型生成引擎配置注销时会同步删除LLM_ENGINES中的对应条目避免残留脏配置。六、列出内置与自定义模型registrations client.list_model_registrations(model_typemodel_type)或通过 CLIxinference registrations --model-type model_typelist_model_registrations见 restful_client.py请求/v1/model_registrations/{model_type}接口detailedTrue时可返回更详细的规格信息。七、启动自定义模型uid client.launch_model(model_namecustom-llama-2, model_formatpytorch)或通过 CLIxinference launch --model-name custom-llama-2 --model-format pytorch启动成功后返回模型 UIDmodel_uid。从源码看restful_client.pylaunch_model支持model_type、model_engine、model_size_in_billions、quantization、replica、n_worker、n_gpu默认autoNone表示纯 CPU、worker_ip、gpu_idx、model_path、enable_virtual_env等丰富参数可灵活适配单机与分布式部署。八、与自定义模型交互model client.get_model(model_uiduid) model.generate(What is the largest animal in the world?)返回结果示例OpenAI 兼容格式{ id:cmpl-a4a9d9fc-7703-4a44-82af-fce9e3c0e52a, object:text_completion, created:1692024624, model:43e1f69a-3ab0-11ee-8f69-fa163e74fa2d, choices:[ { text:\nWhat does an octopus look like?\nHow many human hours has an octopus been watching you for?, index:0, logprobs:None, finish_reason:stop } ], usage:{ prompt_tokens:10, completion_tokens:23, total_tokens:33 } }或通过 CLI将${UID}替换为真实模型 UIDxinference generate --model-uid ${UID}自定义模型启动后走的是与内置模型完全一致的统一推理 API客户端无需关心模型是内置还是自定义这正是「Swap GPT for any LLM by changing a single line of code」的基础。九、注销自定义模型model client.unregister_model(model_typemodel_type, model_namecustom-llama-2)或通过 CLIxinference unregister --model-type model_type --model-name custom-llama-2从 xinference/model/custom.py 的实现看unregister会先从内存注册表移除模型再调用remove_ud_model_files清理持久化文件若模型不存在默认抛ValueError: Model not found。注销后该模型即无法再被启动需重新注册才能使用。十、实践建议与注意事项优先复用内置家族能直接用model_path直启的模型不要注册成本最低注册仅用于内置列表之外的模型。model_uri三选一本地文件file://绝对路径、Hub ID配合model_id/model_hub自动下载、OCI 镜像oci:// llmman。三者是互斥的加载来源。chat 能力必配 chat_template忘记配置chat_template会导致带chat能力的模型无法正确构造 prompt。命名规范model_name只能含字母、数字、下划线和连字符且不能与内置/已注册模型重名否则注册直接失败。持久化与否要想清楚--persist仅适用于需要跨重启保留的场景临时调试建议不持久化避免污染模型目录。虚拟环境隔离依赖特殊的模型如需要特定版 vLLM/transformers可启用virtualenv配置按模型隔离依赖详见 doc/source/models/virtualenv.rst。结语从v0.14.0的model_path直启到v2.0.0的 Web UI 自动解析再到覆盖 LLM / Embedding / Rerank / Image / Audio / Flexible 六类模型的注册体系Xinference 的自定义模型能力已经形成「直启 → 定义 → 注册 → 管理 → 调用 → 注销」的完整闭环。配合 xinference/model/custom.py 中统一的注册表设计与 xinference/client/restful/restful_client.py 中统一的 REST 接口无论模型来自本地、Hub 还是容器镜像都可以用同一套 API 无缝接入生产推理环境。【免费下载链接】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），仅供参考