phi4-mm-gguf 接入 Open WebUI、Continue 等生态:OpenAI 兼容接口集成全清单

原创2026-10-17 20:12:42261 阅读

phi4-mm-gguf 接入 Open WebUI、Continue 等生态:OpenAI 兼容接口集成全清单

phi4-mm-gguf 是微软 5.6B 多模态大模型 Phi-4-multimodal-instruct 的 GGUF 量化版本,支持文本与图像输入。通过 llama.cpp 或 Ollama 在本地起一个 OpenAI 兼容接口(/v1/chat/completions),只需修改 Base URL 和模型名,即可把它接入 Open WebUI、Continue、SillyTavern、OpenClaw 等主流生态,零额外开发。

本文给出一份可直接照抄的集成清单:从选文件、起服务,到各工具连接配置,一步到位。

一、先选文件:Q8_0、Q4_K_M 与 mmproj 怎么搭配

仓库中提供了三种精度的 GGUF 文本模型和一个视觉编码器(完整说明见 README.md):

文件 精度 大小 适用场景
phi4-mm-Q8_0.gguf Q8_0 3.90 GB 高端 GPU,近乎无损
phi4-mm-Q4_K_M.gguf Q4_K_M 2.37 GB CPU / 显存紧张设备
phi4-mm-f16.gguf F16 7.17 GB 重新量化基底,质量最高
mmproj-phi4-mm-f16.gguf F16 825 MB 视觉编码器,图像输入必需

💡 两个关键点:

  • mmproj 是"图像开关":不带它模型只能跑纯文本;带它之后,Open WebUI 等工具里上传的图片才能被真正理解。它兼容上面全部三个文本 GGUF。
  • 显存参考(全部层上 GPU):F16 组合约 10 GB,Q8_0 组合约 5.4 GB,Q4_K_M 组合约 3.5 GB(数据来自 README.md)。

没有本地仓库副本时,可以直接克隆获取模型文件:

git clone https://gitcode.com/hf_mirrors/Swicked86/phi4-mm-gguf

二、一条命令启动 OpenAI 兼容接口(llama-server)

这是接入生态的核心一步。llama-server 会把文本和图像统一暴露到标准的 /v1/chat/completions 端点(命令摘自 README.md):

./build/bin/llama-server \
  -m phi4-mm-Q8_0.gguf \
  --mmproj mmproj-phi4-mm-f16.gguf \
  -ngl 99 --threads 16 \
  --ctx-size 8192 --parallel 4 \
  --port 8080 --host 127.0.0.1

启动后用一条 curl 验证接口是否就绪(文本请求格式见 README.md):

curl http://localhost:8080/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{"model": "phi4-mm",
       "messages": [{"role": "user", "content": "用一句话介绍勾股定理"}],
       "max_tokens": 300}'

能返回 JSON 回答,说明 OpenAI 兼容接口已可用,下面所有生态工具都只需指向它。

图像请求同样走标准格式:把图片转成 base64,以 image_url 类型放入 messages 的 content 数组即可,示例见 README.md。

另外两条启动路线

路线 适合人群 说明
Ollama CPU / NUC / 边缘设备 用 deploy/Modelfile 一条命令注册模型,接口为 http://localhost:11434/v1,完整部署流程见 deploy/README-deployment.md
vLLM 需要音频能力的用户 基于原始 bf16 权重,文本+图像+语音全模态,参数细节见 README.md

⚠️ 注意:GGUF 文件不包含音频编码器,语音转写必须走 vLLM 路线(详见 README.md)。

Ollama 路线只需两行(Modelfile 已针对 8 GB 内存 NUC 调好线程数、上下文与采样参数):

ollama create phi4-mm-nuc -f deploy/Modelfile
ollama run phi4-mm-nuc

仓库还附带了一键部署脚本 deploy/install-nuc.sh,会自动安装 Ollama、注册模型并做冒烟测试。

三、生态接入全清单

服务起来之后,各工具的连接配置大同小异。下面按工具逐一列出。

Open WebUI 接入:3 步加模型

  1. 进入 Open WebUI 的 Settings → Connections,添加 Ollama 连接(Base URL 指向 http://<主机>:11434),或直接添加 OpenAI API 连接,Base URL 填 http://<主机>:8080/v1;
  2. API Key 随便填(如 local),OpenAI 兼容端点不校验;
  3. 刷新模型列表,出现 phi4-mm 后点开对话,即可直接上传图片提问。

走 Ollama 路线时,模型名为 phi4-mm-nuc(由 deploy/install-nuc.sh 注册)。

Continue 接入:本地 OpenAI 兼容代码助手

Continue 支持 OpenAI 兼容的任意端点:在配置的 models 里选择 OpenAI Compatible,填入:

  • Base URL:http://<主机>:8080/v1
  • 模型名:phi4-mm
  • API Key:local

保存后 Continue 的 Chat 与 Inline 补全即可调用本地 phi4-mm,代码库不出内网。

SillyTavern 接入:角色扮演场景

SillyTavern 的 API 管理器中新建一个 OpenAI 类型的 API:Base URL 填 http://<主机>:8080/v1,模型名填 phi4-mm。之后像调用云端模型一样使用它,角色卡、世界书等插件功能全部保留。README 中也明确将 SillyTavern 列为 llama-server 的目标集成对象(README.md)。

OpenClaw 接入:仓库自带配置

仓库直接提供了 OpenClaw 的示例配置 deploy/openclaw-config.json,核心内容是把 agent 指向 Ollama 的本地模型:

"provider": "ollama",
"model": "phi4-mm-nuc",
"baseUrl": "http://localhost:11434"

把该文件放入 OpenClaw 的配置目录(~/.openclaw/)即可让 agent 使用本地多模态模型。

LM Studio 接入:桌面零命令行方案

LM Studio 原生支持 GGUF 多模态:加载 phi4-mm-Q8_0.gguf 后,在 Model Settings → Multimodal → Vision Model (mmproj) 中选择 mmproj-phi4-mm-f16.gguf,聊天窗口上传图片即可对话(步骤见 README.md)。LM Studio 本地同样可开 OpenAI 兼容端口,供其他工具复用。

四、集成配置速查清单

配置项 llama-server 路线 Ollama 路线
Base URL http://<主机>:8080/v1 http://<主机>:11434/v1
模型名(model) phi4-mm phi4-mm-nuc
API Key 任意非空字符串(如 local) 任意非空字符串
图像输入 ✅ 需 --mmproj 参数 ⚠️ GGUF 文本模型为主
音频输入 ❌ GGUF 不支持 ❌ GGUF 不支持
推荐硬件 Q8_0 ≈ 5.4 GB 显存 / Q4_K_M ≈ 3.5 GB 8 GB 内存纯 CPU 可跑

一句话总结:工具端永远只填三样东西——Base URL、模型名、占位 API Key,其余能力(流式、图像、并行请求)都由服务端参数决定。

五、三个高频坑位,先读再连

  1. 上传了图片却没反应:99% 是启动时漏了 --mmproj mmproj-phi4-mm-f16.gguf。视觉编码器不挂载时,接口只会把图片当纯文本忽略(README.md)。
  2. 想要语音转写却 400 报错:GGUF 路线没有音频张量,这是转换管线的固有限制而非配置错误。需要音频请换 vLLM + 原始 bf16 权重(README.md)。
  3. vLLM 工具调用解析失败:phi4-mm 输出的工具调用格式是 functools<a href="https://link.gitcode.com/i/b0580ab42047f63af257c435edcb58c8" target="_blank">...] 而非 Hermes,启动时必须带 --tool-call-parser phi4_mini_json 参数,否则 function calling 无法被解析([README.md)。

📚 延伸阅读:完整的文件列表、VRAM 需求、质量指标(PPL 与吞吐)及全部命令行示例,都整理在主文档 README.md 中;CPU/边缘部署的硬件推荐表见 deploy/README-deployment.md。把 Base URL 填进你的第一个工具,phi4-mm 的多模态能力今天就上线。

登录后查看全文
phi4-mm-gguf