人工智能大模型本地部署模型推理服务【免费下载链接】llama-cpp-pythonPython bindings for llama.cpp项目地址https://gitcode.com/gh_mirrors/ll/llama-cpp-python点击查看免费下载本文以仓库中的 examples/server/README.md 为核心结合其配套实现 examples/server/server.py 与全部配置文件系统讲解 llama-cpp-python 自带的 OpenAI 兼容 Web 服务器如何用uv一键启动、如何编写模型/多模态/投机解码/磁盘缓存配置、如何调用/v1/chat/completions、/v1/responses、/v1/embeddings等端点并深入剖析其批处理调度、响应解析与序列缓存的源码级原理。读完本文你将能够基于任意 GGUF 模型含视觉、音频、工具调用、思维链模型在本地部署一套生产可用的 OpenAI 兼容服务。概览一个只依赖低层 C 绑定的全新服务器examples/server是 llama-cpp-python 仓库中一套经过全面更新的 OpenAI 兼容 Web 服务器示例。与旧的llama_cpp.server模块不同它的核心卖点是只依赖低层 C 绑定llama_cpp.llama_cpp、llama_cpp.llama_cpp_ext、llama_cpp.mtmd_cpp不依赖高层Llama类实现完全自包含见 server.py 顶部 import支持**批处理推理batched inference**与基于 RadixTrie 的prompt 前缀缓存支持响应解析response parsing将模型自由文本稳定地解析成 OpenAI 兼容的结构化字段提供/v1/responsesHTTP 无状态版 WebSocket 有状态版与/v1/embeddings端点支持磁盘序列缓存disk sequence cache、MTP 多 token 预测、LoRA 适配器以及多模态图像/音频/视频输入。整个服务器由单个 server.py约 1.6 万行实现入口main()只接收一个必需参数-C/--config-file见 server.py所有行为均由 JSON 配置文件驱动create_app()负责构建 FastAPI 应用server.py。环境准备与快速启动该服务器是一个uv 内联脚本inline script文件头部#!/usr/bin/env -S uv run --script配合/// script元数据块声明了fastapi、jinja2、llama-cpp-python、numpy、openai、pydantic、safetensors、uvicorn、websockets等依赖。因此uv会自动创建脚本环境并安装 Python 依赖无需手动pip install。最简启动方式默认小模型配置cd examples/server uv run --script server.py -C configs/qwen3.5-0.8b.json如果不想从源码编译llama-cpp-python可以用uv run --extra-index-url拉取预编译二进制 wheelcd examples/server uv run \ --extra-index-url https://abetlen.github.io/llama-cpp-python/whl/cpu \ --script server.py -C configs/qwen3.5-0.8b.json按后端选择 wheel 索引预编译 wheel 按后端分门别类请选择与你的运行环境匹配的索引完整要求参见仓库 README.md#supported-backends后端Wheel 索引CPUhttps://abetlen.github.io/llama-cpp-python/whl/cpuCUDA 11.8https://abetlen.github.io/llama-cpp-python/whl/cu118CUDA 12.1https://abetlen.github.io/llama-cpp-python/whl/cu121CUDA 12.2https://abetlen.github.io/llama-cpp-python/whl/cu122CUDA 12.3https://abetlen.github.io/llama-cpp-python/whl/cu123CUDA 12.4https://abetlen.github.io/llama-cpp-python/whl/cu124CUDA 12.5https://abetlen.github.io/llama-cpp-python/whl/cu125CUDA 13.0https://abetlen.github.io/llama-cpp-python/whl/cu130CUDA 13.2https://abetlen.github.io/llama-cpp-python/whl/cu132Metalhttps://abetlen.github.io/llama-cpp-python/whl/metalROCmhttps://abetlen.github.io/llama-cpp-python/whl/rocm72Vulkanhttps://abetlen.github.io/llama-cpp-python/whl/vulkan模型配置仓库内置的六个示例仓库 examples/server/configs 下内置了 6 个可直接运行的配置。其中最小的 Qwen3.5 0.8B 配置专门用于在普通开发机上快速验证配置模型说明configs/bge-small-en-v1.5.jsonCompendiumLabs/bge-small-en-v1.5-gguf小型嵌入模型配置供/v1/embeddings使用configs/qwen3.5-0.8b.jsonlmstudio-community/Qwen3.5-0.8B-GGUF默认的小型多模态示例configs/gemma-4-12b-it-qat.jsonunsloth/gemma-4-12B-it-qat-GGUF较大的 Gemma 4 QAT 多模态配置带 projectorconfigs/qwen3.6-27b.jsonunsloth/Qwen3.6-27B-GGUF较大的 Qwen3.6 多模态配置configs/qwen3.6-35b-a3b.jsonunsloth/Qwen3.6-35B-A3B-GGUF较大的 Qwen3.6 MoE 多模态配置configs/gpt-oss-120b.jsonggml-org/gpt-oss-120b-GGUF大型纯文本 split-GGUF 配置几个值得注意的细节较大的模型配置默认启用n_gpu_layers: -1全量 GPU 卸载和flash_attn: truegpt-oss-120b.json 展示了split-GGUF 分片下载主filename指向gpt-oss-120b-mxfp4-00001-of-00003.gguf其余两个分片通过from_pretrained.additional_files一并下载bge-small-en-v1.5.json 不配置chat_template和mtmd只保留嵌入所需的n_ctx: 512、n_seq_max: 16等最小运行时参数且store_logits: false。配置文件的三段式结构所有配置文件都只有三个顶层段落{ server: {}, model: {}, disk_cache: {} }段落是否必需作用server否Uvicorn 的 host 与 port 设置model是模型来源、llama.cpp 运行时设置、聊天模板、LoRA、MTMD 多模态、投机解码与输出解析disk_cache否可选的序列化序列缓存用于复用重复的 prompt 前缀对应地server.py 中的ConfigFile定义了ServerOptionshost默认127.0.0.1、port默认8000、DiskCacheOptionsmax_bytes必须非负、min_tokens默认 128 且至少为 1以及FromPretrainedOptions支持additional_files、local_dir、cache_dir等 Hugging Face 下载参数。启动时main()依次解析配置、解析模型路径、加载 LoRA、创建Model、按需创建 MTMD 处理器与磁盘序列缓存最后调用uvicorn.run()server.py。server段绑定地址与端口{ server: { host: 0.0.0.0, port: 8000 } }字段默认值说明host127.0.0.1设为0.0.0.0可将服务暴露到网络port8000直接传给uvicorn.run()model段之模型来源本地路径或 Hugging Facemodel段最核心的是告诉服务器模型从哪来。可以用path指向本地 GGUF也可以用from_pretrained从 Hugging Face 下载{ model: { alias: qwen3.5-0.8b-vl, from_pretrained: { repo_id: lmstudio-community/Qwen3.5-0.8B-GGUF, filename: Qwen3.5-0.8B-Q8_0.gguf } } }字段说明path本地 GGUF 路径from_pretrained.repo_idHugging Face 模型仓库名from_pretrained.filenameGGUF 文件名支持 glob 通配模式from_pretrained.additional_files需从同一仓库额外下载的文件如 split-GGUF 分片from_pretrained.cache_dir可选的 Hugging Face 缓存目录alias/v1/models返回的模型 id也是 OpenAI 兼容客户端使用的模型名从源码看FromPretrainedOptions内部通过huggingface_hub.hf_hub_download实现下载并做了两层容错下载失败时先尝试scan_cache_dir查找缓存再以local_files_onlyTrue回退到本地缓存如果配置了local_dir还会把缓存文件复制到指定目录server.py。Hugging Face 缓存行为与仓库文件解析遵循 huggingface_hub 官方下载约定。llama.cpp 运行时设置model段的大多数运行时字段直接映射到 llama.cpp 头文件llama.h中定义的llama_model_params或llama_context_params结构体。{ model: { n_ctx: 32768, n_seq_max: 64, n_batch: 128, n_ubatch: 128, threads: 4, threads_batch: 8, kv_unified: true, use_mmap: true, use_mlock: true } }字段作用n_ctx总上下文大小token 数n_seq_max最大并发 llama.cpp 序列 id 数量决定可同时服务的请求数n_batch逻辑批容量n_ubatch物理微批microbatch容量threads解码线程数threads_batch预填充prefill与批处理线程数kv_unified选择统一unified还是按序列per-sequence的内存布局embedding覆盖嵌入模式省略时根据模型元数据自动检测带池化的嵌入 GGUFpooling_type覆盖嵌入模型的池化行为例如1表示 mean poolingstore_logits采样或诊断需要时在解码后保留 logitsuse_mmap将模型权重做内存映射use_mlock尝试将模型页锁定进 RAM防止换页从源码看这些字段在main()中几乎一一透传给Model构造器server.pyModel内部再按 llama.cpp C API 组装llama_model_params/llama_context_params并完成上下文初始化ConfigFile中还额外支持rope_scaling_type、rope_freq_base、yarn_*系列、attention_type、max_seq_len、max_output_tokens、type_k/type_v等高级参数server.py可在上下文扩展YaRN与 KV 量化场景下使用。GPU 与后端透传参数设置时GPU 与后端相关字段会直接透传给 llama.cpp{ model: { n_gpu_layers: -1, split_mode: 1, main_gpu: 0, tensor_split: [1.0], flash_attn: true, offload_kqv: true, op_offload: true } }其中n_gpu_layers: -1表示将全部层卸载到 GPUtensor_split用于多 GPU 时按比例切分张量flash_attn、offload_kqv、op_offload分别控制 FlashAttention、KQV 矩阵卸载与算子级卸载。这些字段在Model.__init__中被显式接收并传入底层初始化server.py未设置时保持 llama.cpp 默认值。Chat 模板model.chat_template是一个 Jinja 聊天模板风格与 Hugging Face Transformers 的 chat template 约定兼容。单个字符串写法{ model: { chat_template: {{ bos_token }}{{ messages[0].content }}{{ eos_token }} } }当模板过大、不便在单行 JSON 字符串中阅读或编辑时可以用字符串数组分段拼接{ model: { chat_template: [ {{ bos_token }}, {{ messages[0].content }}, {{ eos_token }} ] } }仓库自带的 configs/qwen3.5-0.8b.json 包含一份完整的 Qwen3.5 模板以数组形式组织支持推理文本reasoning、工具调用tool calls、强制工具选择forced tool choice、图像标记image markers与视频标记video markers模板中还通过enable_thinking/reasoning_effort控制思考模式并把工具响应包装成tool_response结构以便多步工具调用。gpt-oss-120b.json 则内置了 gpt-oss 风格的多 channel 模板analysis / commentary / final将工具的 TypeScript 类型定义渲染进 system 提示中。服务器端通过Jinja2ChatFormatterserver.py在受控沙箱环境中渲染模板。响应解析把自由文本变成 OpenAI 兼容字段model.response_schema用于把模型生成的文本解析为 OpenAI 兼容字段。它基于JSON Schema并叠加 Hugging Face 的x-regex扩展正则约束 命名捕获组提取{ model: { response_schema: { type: object, properties: { role: {const: assistant}, content: { type: string, x-regex: ^(.*)$ } }, required: [role] } } }要点x-regex中^...$之间的部分是命名捕获组用于从生成文本中截取对应字段x-regex-iterator与x-regex-key-value用于解析重复出现的工具调用块前者按迭代器正则切出每个tool_call.../tool_call块后者把parameternamevalue/parameter键值对解析为 JSON 对象实际配置远比示例复杂qwen3.5-0.8b.json 用它分离reasoning_contentthink.../think内文本、content与结构化tool_calls函数名、参数对象gpt-oss-120b.json 则用它解析|channel|analysis|message|...多 channel 文本并对参数对象使用x-parser: json直接做 JSON 解析。除了响应后解析服务器还支持结构化输出约束源码中的JsonSchemaConverterserver.py能把 JSON Schema 递归编译为 llama.cpp 的GBNF 文法覆盖object、array、string、number、integer、boolean、null、enum、const、oneOf/anyOf/allOf、pattern、minLength/maxLength、minItems/maxItems、additionalProperties、$ref等关键字其中远程$ref取指被显式禁止并支持uuid、date-time等 format——这意味着你可以让模型边生成边被文法约束从根本上保证 JSON 合法。这解释了文档中grammar-backed JSON output的说法。多模态model.mtmdmodel.mtmd加载 llama.cpp 的多模态投影器multimodal projector启用 OpenAI 风格的图像、音频、视频 content parts{ model: { mtmd: { mmproj_from_pretrained: { repo_id: lmstudio-community/Qwen3.5-0.8B-GGUF, filename: mmproj-Qwen3.5-0.8B-BF16.gguf }, embedding_cache: { path: .cache/mtmd-embeddings, max_bytes: 1073741824 }, batch_max_tokens: 1024, image_max_bytes: 20971520, audio_max_bytes: 104857600, video_max_bytes: 536870912, image_timeout_seconds: 10.0 } } }字段作用mmproj_path本地多模态投影器路径mmproj_from_pretrained投影器的 Hugging Face 来源repo_idfilenameembedding_cache.path图像/音频/视频嵌入的缓存目录embedding_cache.max_bytes嵌入缓存的最大字节数batch_max_tokens每次 MTMD 投影器侧编码批处理的最大媒体输出 token 数image_max_bytes图像负载的最大字节数audio_max_bytes音频负载的最大字节数video_max_bytes视频负载的最大字节数image_timeout_seconds远程图像/音频/视频 URL 拉取的超时时间秒源码层面的佐证MTMDProcessorserver.py接收mmproj_path、batch_max_tokens、allowed_media_domains、allowed_local_media_path及各负载上限负责媒体加载与投影器编码MTMDEmbeddingCacheserver.py用safetensors持久化媒体嵌入并以模型文件指纹 mmproj 文件指纹fingerprint_file基于路径/大小/mtime 的 SHA-256作为缓存版本键换模型后缓存自动失效main()中还有一条硬性校验——启用 MTMD 时若模型没有 GGUF 内嵌聊天模板chat_formatter is None将直接抛错server.py。发送图像输入按 OpenAI 聊天 content parts 格式发送{ messages: [ { role: user, content: [ {type: text, text: Describe this image.}, {type: image_url, image_url: {url: https://example.com/image.jpg}} ] } ] }发送音频输入音频既可以用 URL也可以用 base64input_audio{ messages: [ { role: user, content: [ {type: text, text: Transcribe this audio.}, {type: input_audio, input_audio: {data: ...base64..., format: wav}} ] } ] }媒体加载安全策略远程媒体默认策略是白名单制远程http:/https:媒体 URL 在未设置allowed_media_domains时不受限制设置后只允许精确匹配的域名{ model: { mtmd: { allowed_media_domains: [example.com, static.example.com] } } }本地file:媒体 URL默认禁用除非设置allowed_local_media_path{ model: { mtmd: { allowed_local_media_path: /srv/llama-cpp-python/media } } }allowed_media_domains是精确主机名匹配不支持通配符如*.example.com无效。源码中域名被统一小写后存入集合做精确比对server.py。LoRA 适配器model.lorasLoRA 适配器在启动时一次性加载可来自本地文件或 Hugging Face{ model: { loras: [ { from_pretrained: { repo_id: example/qwen-lora-gguf, filename: adapter.gguf }, scale: 1.0 } ] } }需要注意当前实现不支持按请求热切换 LoRA——适配器在进程启动时固定挂载scale控制适配器权重缩放系数。投机解码Draft Decoding设置model.draft_model即可启用投机解码speculative decoding用一个小/快的 draft 模型预测 token再由主模型批量验证。Prompt Lookup Decoding免模型基于 n-gram 匹配的免训练 draft 方案——直接在输入中查找重复片段作为候选 token{ model: { draft_model: prompt-lookup-decoding, draft_model_num_pred_tokens: 8, draft_model_max_ngram_size: 4 } }源码实现位于PromptLookupDecodingserver.py它用滑动窗口在input_ids中从大到小匹配 n-gram命中后把后续 token 作为 draft 输出完全不需要额外模型。MTPMulti-Token Prediction多 token 预测当加载的模型与 llama.cpp 构建版本提供所需 draft 状态时可以使用 MTP{ model: { draft_model: draft-mtp, draft_model_num_pred_tokens: 2, draft_model_threads: 4, draft_model_threads_batch: 8 } }默认情况下draft-mtp从目标模型自身创建 MTP 上下文如果模型使用独立的 assistant GGUF需设置draft_model_path或draft_model_from_pretrained{ model: { draft_model: draft-mtp, draft_model_num_pred_tokens: 2, draft_model_from_pretrained: { repo_id: example/gemma-assistant-GGUF, filename: assistant.gguf } } }MTP 目前只适用于纯文本请求。源码层面MTPDraftProviderserver.py会校验 draft 模型输出嵌入维度必须与目标模型一致并通过llama_get_ctx_other判断是否与目标上下文共享内存is_mem_shared据此决定链式头chain heads与采样批处理模式n_mtp_layers来自llama_model_n_layer_nextn链式头模式下num_pred_tokens会被限制不超过 MTP 层数。磁盘序列缓存disk_cachedisk_cache把 llama.cpp 的序列状态序列化到磁盘供重复的 prompt 前缀复用可显著降低相似请求的 prefill 成本{ disk_cache: { path: .cache/sequences, max_bytes: 1073741824, min_tokens: 128 } }字段作用path缓存序列文件的目录max_bytes缓存最大字节数超出后由后台清理按条目移除min_tokens值得保存的最小前缀长度默认 128实现要点源码佐证SequenceDiskCacheserver.py以目录为后端每个条目保存 token 序列、序列状态张量与可选的 prompt logits文件头记录sequence_cache_format版本1与compatibility_keycompatibility_key由模型与上下文兼容性数据生成compatibility_key_for_model并辅以fingerprint_file路径大小mtime 的 SHA-256——缓存按模型版本隔离应视为临时数据换模型/升级构建后旧缓存不兼容缓存内部用RadixTrieserver.py组织所有序列的公共前缀支持extend、truncate、copy、tokens等操作实现请求之间共享前缀的追加式缓存对应的命中/保存/失败/加载 token 数等指标会汇入/metrics见下。API 端点全景服务器暴露以下 OpenAI 兼容端点路由定义见 server.py端点用途说明POST /v1/completions传统文本补全支持流式、停止序列、logprobs、惩罚、seed以及基于文法的 JSON 输出POST /v1/embeddingsOpenAI 兼容嵌入面向嵌入模式 GGUF 模型支持字符串/ token 输入、base64 输出、维度截断POST /v1/chat/completions聊天补全支持流式、工具、强制工具选择、推理解析、多模态 content parts、结构化响应解析POST /v1/responsesResponses API 兼容无状态版面向使用 response items 与 response events 的客户端WS /v1/responsesResponses WebSocket 传输有状态版每个连接内支持previous_response_id回放GET /v1/models模型列表返回配置的模型 aliasGET /healthz健康检查返回简单类型化健康响应GET /metricsPrometheus 指标以 Prometheus 文本格式暴露调度器、缓存、draft 与模型指标请求参数与校验细节源码佐证CreateCompletionRequestserver.py默认temperature0.8、top_p0.95presence_penalty/frequency_penalty取值范围[-2.0, 2.0]n为生成条数best_of默认等于n且不得小于n流式模式下不支持best_of 1与多 promptlogit_bias的 key 必须是可解析的整数 token id。CreateEmbeddingRequestserver.pyencoding_format支持float/base64dimensions用于截断维度字符串输入不允许为空、单 token 列表不超过 2048 个 token、数组不超过 2048 个条目。WebSocket 版/v1/responsesserver.py维护每连接的历史previous_response_id会在服务端把之前的 output items 归一化后拼接到当前 input 之前从而在一个实时会话内支持多轮上下文这也是 Codex 类客户端的典型用法。客户端调用示例把任意 OpenAI 兼容客户端指向本地/v1即可。Chat Completionsfrom openai import OpenAI client OpenAI(base_urlhttp://127.0.0.1:8000/v1, api_keynot-used) response client.chat.completions.create( modelqwen3.5-0.8b-vl, messages[{role: user, content: What is the capital of France?}], ) print(response.choices[0].message.content)Responses APIfrom openai import OpenAI client OpenAI(base_urlhttp://127.0.0.1:8000/v1, api_keynot-used) response client.responses.create( modelqwen3.5-0.8b-vl, inputWrite one sentence about why prefix caching helps batched inference., ) print(response.output_text)Embeddings——先以嵌入配置启动服务器cd examples/server uv run --script server.py -C configs/bge-small-en-v1.5.jsonfrom openai import OpenAI client OpenAI(base_urlhttp://127.0.0.1:8000/v1, api_keynot-used) response client.embeddings.create( modelbge-small-en-v1.5, input[The food was delicious., The meal was excellent.], ) print(len(response.data[0].embedding))可观测性/metrics与调度器指标GET /metrics以 Prometheus 文本格式输出指标由SchedulerMetricsserver.py与CompletionScheduler.render_prometheus_metricsserver.py共同产生主要分为四类调度器与吞吐llamacpp:prompt_tokens_total、llamacpp:tokens_predicted_total及各自的耗时累计可推导 prefill/解码吞吐n_busy_slots_per_decode反映批内平均并发序列数draft/投机解码draft_process_calls_total、draft_generate_calls_total、draft_batches_verified_total、draft_target_tokens_verified_total、draft_target_tokens_wasted_total等用于评估投机解码的接受率与浪费缓存sequence_cache_hits_total、sequence_cache_save_requests_total、sequence_cache_tokens_loaded_total、checkpoint_hits_total/checkpoint_saves_total/checkpoint_evictions_total模型级请求提交/准入/完成/取消/失败计数以及采样耗时等。/healthz返回类型化的健康响应GET /v1/models返回配置的alias未设置时回退为模型路径owned_by固定为llama-cpp-pythonserver.py。批处理与前缀缓存调度器源码速览CompletionSchedulerserver.py是服务器的核心引擎它把每个请求拆成prefill提示填充与decode逐 token 解码两类BatchItem在每次调度步中把多个请求的 prefill/decode 合并进同一批 llama.cpp batch 提交prefill 项携带 tokens/embeddings、位置信息、prompt_advance_to缓存命中时跳过已缓存前缀、non_causal媒体编码等decode 项携带accepted_draft_count投机解码接受数、rollback_*回滚状态、deferred_*延迟接受/截断等批内 token 总数由batch_token_count统计供指标与预算控制使用。RadixTrie则负责跨请求共享 prompt 前缀多个请求以不同 sequence id 挂到同一前缀节点上命中缓存的前缀可直接复用 KV 状态这正是文档所说batched inference prompt caching的底层机制SchedulerMetrics.observe_decode会按 prefill/生成 token 占比分摊耗时确保吞吐统计准确。小结examples/server是一套自包含、配置驱动的 OpenAI 兼容推理服务器与仓库其他示例不同它完全构建在 llama.cpp 低层 C 绑定之上能力覆盖批处理、前缀缓存、结构化输出、工具调用、多模态、投机解码与磁盘序列缓存。上手只需两步选一个后端匹配的 wheel 索引用uv启动 server.py再按本文所述编写或复用 examples/server/configs 下的 JSON 配置随后任何 OpenAI 兼容客户端即可通过/v1基地址接入。若需深入扩展可结合 examples/server/server.py 中的CompletionScheduler、RadixTrie、JsonSchemaConverter、SequenceDiskCache与MTMDProcessor等实现继续研究。赞分享人工智能大模型本地部署模型推理服务【免费下载链接】llama-cpp-pythonPython bindings for llama.cpp项目地址https://gitcode.com/gh_mirrors/ll/llama-cpp-python点击查看免费下载相关推荐langchain/cohere 1.0 版本线演进解析从 streamEvents 原生转换到 Abort 信号处理的变更全记录langchain/cohere 1.0 版本线演进解析从 streamEvents 原生转换到 Abort 信号处理的变更全记录 本文基于 langch人工智能大模型本地部署模型推理服务llama-cpp-python 实战指南Python 绑定 llama.cpp 的安装配置、高级 API 与 OpenAI 兼容服务器llama cpp python 实战指南Python 绑定 llama.cpp 的安装配置、高级 API 与 OpenAI 兼容服务器 本指南以仓库根目录的人工智能大模型本地部署模型推理服务在 ik_llama.cpp 中使用 llama-cpp-python可行性、替代方案与 OpenAI 兼容接口实战指南在 ik_llama.cpp 中使用 llama cpp python可行性、替代方案与 OpenAI 兼容接口实战指南 导读 llama cpp pyt人工智能大模型推理引擎本地部署模型量化上一篇OpenCreator 10个常见问题终极排错指南连接失败、任务无输出等新手必避的坑下一篇免费网盘直链下载怎么用3步上手这个开源下载助手创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
