phi4-mm-gguf 接入 Open WebUI、Continue 等生态:OpenAI 兼容接口集成全清单
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 步加模型
- 进入 Open WebUI 的 Settings → Connections,添加 Ollama 连接(Base URL 指向
http://<主机>:11434),或直接添加 OpenAI API 连接,Base URL 填http://<主机>:8080/v1; - API Key 随便填(如
local),OpenAI 兼容端点不校验; - 刷新模型列表,出现
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,其余能力(流式、图像、并行请求)都由服务端参数决定。
五、三个高频坑位,先读再连
- 上传了图片却没反应:99% 是启动时漏了
--mmproj mmproj-phi4-mm-f16.gguf。视觉编码器不挂载时,接口只会把图片当纯文本忽略(README.md)。 - 想要语音转写却 400 报错:GGUF 路线没有音频张量,这是转换管线的固有限制而非配置错误。需要音频请换 vLLM + 原始 bf16 权重(README.md)。
- 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 的多模态能力今天就上线。