企业官网建设流程全解析

Xinference 部署 deepseek-coder 完整指南：14 种模型规格、启动命令与源码级解析

【免费下载链接】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 内置的 deepseek-coder 是一组从 2T tokens（87% 代码 + 13% 中英文自然语言）从头训练的代码语言基础模型，提供 1.3B / 6.7B / 7B / 33B 四个规格，并以 pytorch、ggufv2、gptq、awq 四种模型格式共 14 个 Model Spec 上架。本文完整覆盖其模型规格清单与逐一可复制的xinference launch命令，并结合 llm_family.json、llm_family.py 与 cmdline.py 的源码，讲清--size-in-billions下划线语义、引擎校验与规格匹配等底层机制，帮助你正确选规格、写命令并排查常见启动错误。

一、模型概览：deepseek-coder 的基础元数据

在开始部署前，先明确该模型在 Xinference 内置目录中的关键元数据（来源：doc/source/models/builtin/llm/deepseek-coder.rst 与 llm_family.json）：

从源码结构看，model_ability仅标记为generate意味着 API 侧不会为它挂载聊天模板（BUILTIN_LLM_PROMPT_STYLE只服务于 chat 家族，见 llm_family.py）。因此 deepseek-coder 适合作为补全/生成型模型调用；若需要指令对话能力，应选用仓库中同样内置的deepseek-coder-instruct家族（在 llm_family.json 中紧随其后定义，描述为"initialized from deepseek-coder-base and fine-tuned on 2B tokens of instruction data"）。

二、14 个 Model Spec 完整清单

deepseek-coder 的完整规格定义在 llm_family.json 的model_specs数组中。按下表可以一次看清"哪种格式 × 哪个规格 × 哪些量化 × 哪些引擎"的组合矩阵：

2.1 pytorch 格式（原始权重，量化为 none）

要点：

• pytorch 格式的quantization只有none一种，即全精度原始权重；
• 注意大小写与命名差异：官方 7B 版本命名为7b-base-v1.5，而 1.3B / 6.7B / 33B 为*-base；
• 7B 的 v1.5 版本在 llm_family.json 中仅登记了 huggingface 源，未登记 modelscope 源。

2.2 ggufv2 格式（llama.cpp 引擎专用）

ggufv2 格式只能搭配 llama.cpp 引擎，且每条 spec 携带model_file_name_template（如 llm_family.json 中的deepseek-coder-1.3b-base.{quantization}.gguf），Xinference 下载时会将{quantization}占位符替换为你在--quantization中选择的值，只下载对应量化文件而非整个 GGUF 仓库。

2.3 gptq / awq 格式（Int4 权重量化）

gptq 与 awq 均只支持Int4一种量化，引擎同样是 vLLM、Transformers、SGLang 三选一；注意 gptq/awq 均无 7B 规格（7B 只出现在 pytorch 与 ggufv2 中）。

三、启动命令：从占位符到可执行

每个 Model Spec 对应一条启动命令模板。命令中的两个占位符含义如下（参数定义见 cmdline.py）：

• ${engine}：替换为该 spec 的 Engines 列表之一。pytorch/gptq/awq 可选vLLM、Transformers、SGLang（大小写不敏感，见下文源码分析）；ggufv2 只能填llama.cpp。
• ${quantization}：替换为该 spec 的 Quantizations 列表之一。pytorch 填none；gptq/awq 填Int4；ggufv2 填对应 GGUF 量化档位。

各格式的代表性完整命令：

pytorch 全精度（以 33B 为例）：

xinference launch --model-engine vLLM --model-name deepseek-coder --size-in-billions 33 --model-format pytorch --quantization none

1.3B pytorch（注意下划线大小写法）：

xinference launch --model-engine vLLM --model-name deepseek-coder --size-in-billions 1_3 --model-format pytorch --quantization none

ggufv2 + llama.cpp（以 7B Q4_K_M 为例）：

xinference launch --model-engine llama.cpp --model-name deepseek-coder --size-in-billions 7 --model-format ggufv2 --quantization Q4_K_M

gptq / awq Int4（以 33B GPTQ 为例）：

xinference launch --model-engine vLLM --model-name deepseek-coder --size-in-billions 33 --model-format gptq --quantization Int4

xinference launch --model-engine vLLM --model-name deepseek-coder --size-in-billions 6_7 --model-format awq --quantization Int4

--model-name、--model-engine、--size-in-billions、--model-format、--quantization五个核心参数的 CLI 定义位于 cmdline.py，其余可选参数（如--n-gpu、--n-worker、--replica、--model-uid）在同一处定义，可按需追加。

3.1 为什么--size-in-billions要写1_3而不是1.3

这是本文最容易踩的坑。1_3是 Xinference 对"1.3B"的编码方式：

1. CLI 层保留字符串：cmdline.py 中，只有当取值既不含_也不含.时才转换为 int；1_3会原样以字符串传给后端，避免int("1_3")被解释成 18；
2. 规格层保留下划线：llm_family.py 的 spec 校验器同样以"含_保持字符串、否则转 int"的规则处理model_size_in_billions，注释明确写道'1_8' just returns '1_8', otherwise int('1_8') returns 18；
3. 匹配时归一化：实际匹配由 match_model_size 完成——两侧取值都将_替换为.后再比较，整数部分再尝试按 int 相等比较。所以1_3与 JSON 中的"1_3"、33与33都能正确命中；而 convert_model_size_to_float 则在需要浮点语义（如显存估算）时把1_3转成1.3。

因此 1.3B 和 6.7B 两个规格必须使用1_3/6_7的下划线写法；7B 与 33B 则直接写整数7/33。

3.2 引擎与规格的校验链路

启动请求最终会经过两道校验，理解它们可以解释绝大多数"Model ... cannot be run on engine ..."报错：

1. LLM 必须显式指定引擎：cmdline.py 中，--model-type默认为LLM，若--model-engine为 None 直接抛出ValueError: --model-engine is required for LLM models.；
2. 引擎-格式-规格-量化四元组匹配：check_engine_by_spec_parameters 按model_name → model_engine → (model_format, model_size_in_billions, quantizations)逐层查找。其中引擎名匹配是大小写不敏感的（get_model_engine_from_spell会先做 lowercase 比对），所以--model-engine vllm与--model-engine vLLM等效；但四元组任一不匹配就会抛出形如Model deepseek-coder cannot be run on engine llama.cpp, with format pytorch, size 33 and quantization none.的错误——例如把 ggufv2 的量化档位填到 pytorch 格式上、或对 7B 使用 gptq 格式都会命中该分支；
3. 规格解析：match_llm 在BUILTIN_LLM_FAMILIES+ 用户注册家族中按名字、格式、大小、量化（大小写不敏感）逐一过滤，未指定量化时 pytorch 格式默认取none、其他格式取 spec 自带量化，并支持通过{quantization}模板展开model_id。

另外，llm_family.json 中该家族还声明了按引擎区分的 virtualenv 依赖（#transformers_dependencies# ; #engine# == "Transformers"、#vllm_dependencies# ; #engine# == "vllm"等），配合 check_engine_by_spec_parameters_with_virtual_env 的引擎标记校验，保证启用虚拟环境时所选引擎确实登记在该模型的依赖清单中。

3.3 本地缓存目录命名

模型文件按"名称-格式-大小b-量化"组织在缓存目录中，构造逻辑见 _get_cache_dir_for_model_mem，例如 6.7B pytorch 的目录形如deepseek-coder-pytorch-6_7b-none。这也解释了为什么--size-in-billions的下划线必须与 JSON 登记值保持一致：它是缓存路径的一部分。

四、规格选择建议与常见错误排查

结合上文清单与源码行为，给出实操性建议：

1. 有 GPU 且追求吞吐：pytorch + vLLM/SGLang 全精度（小规格）或 gptq/awq Int4（33B 大规格）；量化后显存占用显著下降，引擎支持相同；
2. CPU 或无 GPU 环境：ggufv2 + llama.cpp，量化档位按内存预算选择——Q4_K_M是通用折中，Q8_0质量上限更高但内存占用接近全精度；
3. 需要对话/指令能力：deepseek-coder 的 ability 仅为generate，指令场景请改用内置的 deepseek-coder-instruct；
4. 常见报错对照：
   • 缺--model-engine→ 见 3.2 第 1 条，CLI 强制要求；
   • cannot be run on engine ...→ 四元组不匹配，核对--model-format与--quantization是否取自同一 spec 行（如 7B 没有 gptq/awq 规格，ggufv2 只能用 llama.cpp）；
   • 大小写混用：量化与引擎名匹配均不区分大小写（见 match_llm 中的_match_quantization），但--size-in-billions必须与 JSON 登记值逐字符一致（1_3/6_7/7/33）。

五、延伸阅读

• 家族级原始定义：llm_family.json（含context_length、model_lang、architectures、virtualenv等字段）；
• instruct 版本定义：llm_family.json；
• 规格匹配与引擎校验实现：llm_family.py；
• CLI 参数定义与 LLM 引擎强校验：cmdline.py；
• 相关文档入口：内置 LLM 模型文档目录，以及同系列的 deepseek-coder-instruct 页面（如该文件存在于仓库中）。

以上全部内容以当前仓库中的模型目录与 CLI 源码为准；实际可下载的具体量化文件以模型源仓库为准，本文不对外部站点作可用性承诺。

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