Xinference 中运行 CodeGeeX4：PyTorch 与 GGUF 双格式的编程大模型实战指南

Xinference 中运行 CodeGeeX4：PyTorch 与 GGUF 双格式的编程大模型实战指南

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

CodeGeeX4 是智谱 AI 开源的最新 CodeGeeX 系列模型之一，专为代码补全、代码生成与编程问答场景设计。本文以 Xinference 内置模型注册表中codegeex4的官方文档为基础，结合 xinference/model/llm/llm_family.json 中的真实注册数据与 xinference/deploy/cmdline.py 的命令行解析实现，系统讲解该模型在 Xinference 中的两种可部署规格（PyTorch 全精度版与 GGUF 量化版）、支持的推理引擎与量化档位，并给出可直接复制运行的启动命令。读完本文，你将掌握在 Xinference 中一键拉起 CodeGeeX4、按硬件条件选择合适引擎与量化方式，以及理解引擎—格式匹配规则的完整能力。

模型概览：CodeGeeX4 的官方内置定义

在 Xinference 中，内置 LLM 的全部元信息（上下文长度、语言、能力、规格、量化、模型 ID、对话模板、停止 token 等）都集中维护在模型家族注册表 xinference/model/llm/llm_family.json 中，codegeex4条目位于该文件第 4305 至 4395 行。官方文档 doc/source/models/builtin/llm/codegeex4.rst 正是由注册表数据自动生成的，其模板见 doc/templates/llm.rst.jinja。

该模型的顶层元信息如下：

几个值得注意的细节：

• 131072 的上下文长度意味着模型原生支持 128K 级别的长上下文，适用于大仓库代码分析、长文件重构等场景；
• 能力仅有chat（对话），不包含generate（补全）能力——这与 CodeGeeX4-All-9B 定位"全能对话模型"而非纯补全模型的特性一致，后续引擎匹配逻辑也会基于该能力集合做校验；
• 注册表字段featured: false，表明它属于常规内置模型，并非官方置顶展示模型。

规格一：PyTorch 全精度版（9B，无量化）

官方文档中第一个 Model Spec 对应 PyTorch 格式的 9B 全精度模型，注册表数据位于 xinference/model/llm/llm_family.json：

启动命令如下（将${quantization}替换为none，将${engine}替换为vllm或transformers）：

xinference launch --model-engine ${engine} --model-name codegeex4 --size-in-billions 9 --model-format pytorch --quantization ${quantization}

关于该规格的补充说明：

• 由于quantizations仅列出none，实际执行时必须写--quantization none；
• 注册表为 Hugging Face 与 ModelScope 两个模型仓库分别记录了model_id与model_revision，Xinference 会根据你配置的模型源（Hugging Face 或 ModelScope）自动从对应仓库下载权重，无需手工指定路径；
• vLLM 引擎依赖 CUDA 环境与#vllm_dependencies#包集合（见下文"依赖与虚拟环境"），而 Transformers 引擎更通用，在仅 CPU 或受限 GPU 环境下也能加载，但推理吞吐通常低于 vLLM。

规格二：GGUF v2 量化版（9B，六档量化）

第二个 Model Spec 是 GGUF v2 格式的量化版本，注册表数据位于 xinference/model/llm/llm_family.json：

启动命令如下（${quantization}从上方六档中选择其一，${engine}为vllm或llama.cpp）：

xinference launch --model-engine ${engine} --model-name codegeex4 --size-in-billions 9 --model-format ggufv2 --quantization ${quantization}

该规格的核心价值在于按显存预算弹性选择精度：

• IQ2_M / IQ3_M：极致压缩档，显存占用最低，适合小显存显卡或纯 CPU 推理，精度损失相对明显；
• Q4_K_M / Q5_K_M：性价比平衡档，K-M 变体对关键张量采用更高精度，是社区最常用的组合，建议作为默认选择；
• Q6_K_L / Q8_0：高精度档，Q8_0 接近全精度效果，显存占用也最高。

量化档位与 GGUF 文件名严格对应：注册表中定义了model_file_name_template为codegeex4-all-9b-{quantization}.gguf，即下载时会按所选量化自动定位到codegeex4-all-9b-Q4_K_M.gguf这类具体文件，因此量化名称必须与上述六档完全一致，否则无法匹配到模型文件。

引擎与格式的匹配规则：为什么 GGUF 只能用这两个引擎

在选择引擎时，Xinference 会执行格式—引擎兼容性校验，核心逻辑位于 xinference/model/llm/init.py 的check_format_with_engine：

def check_format_with_engine(model_format, engine): # only llama-cpp-python support and only support ggufv2 if model_format in ["ggufv2"] and engine not in ["llama.cpp", "vLLM"]: return False if model_format not in ["ggufv2"] and engine == "llama.cpp": return False return True

这条规则直接解释了官方文档中两个 Spec 的引擎列表差异：

1. ggufv2格式只能配llama.cpp或vLLM：GGUF 是 llama.cpp 生态的量化格式，因此以llama.cpp（经xllamacpp绑定）加载最为自然；vLLM 在较新版本中也支持直接加载 GGUF 文件，故同样被允许。若试图对 ggufv2 指定transformers引擎，会被该校验直接拒绝；
2. llama.cpp引擎只能加载ggufv2格式：因此 PyTorch 规格无法使用llama.cpp引擎，只能走 vLLM 或 Transformers。

此外，xinference/model/llm/llama_cpp/core.py 中 llama.cpp 引擎的match_json校验还要求模型必须具有chat或generate能力，而codegeex4恰好具备chat能力，满足要求。综合来看，可用的引擎—格式组合为：PyTorch → vLLM / Transformers，GGUF v2 → vLLM / llama.cpp。

启动命令参数逐项解读

官方文档给出的启动命令对应 xinference/deploy/cmdline.py 中xinference launch的 CLI 参数定义，各参数含义与命令行选项如下：

同时需要注意 xinference/deploy/cmdline.py 中的强制校验：对于 LLM 类型模型，--model-engine为必填项，缺失时会直接抛出ValueError。这一点与文档中"记得把${engine}替换为你选择的引擎"的提示相互印证——启动 CodeGeeX4 时不要省略该参数。

常见启动示例

以 4-bit 量化在 llama.cpp 引擎下启动（CPU/低显存友好）：

xinference launch --model-engine llama.cpp --model-name codegeex4 \ --size-in-billions 9 --model-format ggufv2 --quantization Q4_K_M

以全精度在 vLLM 引擎下启动（GPU 吞吐优先，需满足约 9B 全精度的显存要求）：

xinference launch --model-engine vllm --model-name codegeex4 \ --size-in-billions 9 --model-format pytorch --quantization none

依赖与虚拟环境：不同引擎的自动装配

从注册表第 4387 至 4394 行可以看到，codegeex4为每个引擎声明了独立的条件依赖，Xinference 在启动模型时会按所选引擎自动创建/复用虚拟环境并安装对应依赖包：

#transformers_dependencies# ; #engine# == "Transformers" #llama_cpp_dependencies# ; #engine# == "llama.cpp" #vllm_dependencies# ; #engine# == "vllm" #system_numpy# ; #engine# == "vllm"

也就是说：选择 Transformers 引擎时会装配 transformers 依赖链；选择 llama.cpp 引擎时装配#llama_cpp_dependencies#（其底层绑定为xllamacpp，见 xinference/model/llm/llama_cpp/core.py 中从xllamacpp导入Server、estimate_gpu_layers等实现）；选择 vLLM 引擎时除 vLLM 依赖外还会额外携带系统级 numpy。这一机制保证你无需手工管理多套引擎环境，换引擎时由 Xinference 自动完成依赖隔离与装配，虚拟环境管理细节可参考 xinference/core/virtual_env_manager.py 与文档 doc/source/models/virtualenv.rst。

对话模板与停止 Token：保证生成质量的隐藏配置

除了规格信息，注册表还为codegeex4配置了完整的对话协议（xinference/model/llm/llm_family.json）：

• chat_template：采用ChatGLM风格的<|system|>/<|user|>/<|assistant|>角色标记；当首条消息不是 system 消息时，会自动注入 CodeGeeX 的默认系统提示词"你是一位智能编程助手，你叫CodeGeeX。你会为用户回答关于编程、代码、计算机方面的任何问题，并提供格式规范、可以执行、准确安全的代码，并在必要时提供详细的解释。"；
• stop_token_ids：[151329, 151336, 151338]；
• stop：["<|endoftext|>", "<|user|>", "<|observation|>"]。

这套配置由 Xinference 在请求处理时自动套用，因此通过统一的 OpenAI 兼容 API 调用 CodeGeeX4 时，多轮对话的角色拼接、结束符处理均已开箱即用，无需在客户端侧手写模板。

实战选型建议

综合上述分析，在不同场景下的推荐组合如下：

1. 有充足 GPU 显存、追求最佳效果与吞吐：选 PyTorch 规格 + vLLM 引擎（--quantization none），适合生产级代码问答服务；
2. 显存受限或 CPU 部署：选 GGUF v2 规格 + llama.cpp 引擎，量化档位从Q4_K_M起步逐步试调，兼顾体积与质量；
3. 对部署灵活性要求高：PyTorch 规格 + Transformers 引擎，可在更宽泛的硬件环境中运行，代价是吞吐相对较低；
4. 长上下文代码分析：两个规格均保持 131072 的上下文窗口，注意在 vLLM 下合理设置--max-num-seqs等批处理参数以控制 KV Cache 占用。

无论选择哪种组合，启动后都可以用 xinference/client/restful/restful_client.py 提供的统一客户端，或标准的 OpenAI 兼容接口发起对话请求，验证模型是否按预期工作。相关运行与验证的通用流程可进一步参考 doc/source/getting_started/using_xinference.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