EN ID MS TH TL VI ZH

hy4 Ollama 接入：把本地混元接进 Dify / Cursor / 任意 OpenAI 兼容客户端

用 Ollama 跑起本地 hy4 之后，怎么把它接进你的工具链：Modelfile 导入本地 GGUF、启动服务、给 Dify / Cursor / Open WebUI 配本地端点、设置模型名映射，以及 OpenAI 兼容客户端的 base_url 写法与常见故障排查。

hy4 Ollama 接入：把本地混元接进 Dify / Cursor / 任意 OpenAI 兼容客户端

把 hy4 跑起来只解决了一半问题——真正影响日常体验的是它能不能被你的工具链调用。Ollama 在这件事上的价值是：它自带一整套模型管理与 OpenAI 兼容端点，Dify、Cursor、Open WebUI、Continue 这类工具默认就认它，不需要改代码。本文给一条完整链路：从本地 GGUF 导入，到服务化，到客户端配置，再到故障排查。

30 秒版本

ollama create 用 Modelfile 导入本地 GGUF → ollama serve 起 11434 端口 → 客户端把 base URL 指向 http://127.0.0.1:11434/v1、Key 随便填 → 用 /v1/models 拉模型列表做校验。Dify、Cursor、Open WebUI 都走 OpenAI 兼容协议，改配置即可接入。

第一步：准备 GGUF 权重

bash

mkdir -p ~/models && cd ~/models
huggingface-cli download bartowski/tencent_Hunyuan-4B-Instruct-GGUF \
  Q4_K_M.gguf --local-dir .
ls -lh

为什么推荐社区 GGUF 而不是官方量化

官方给的是 FP8、GPTQ-Int4、AWQ-Int4，这些格式要 vLLM 之类的服务化栈才能吃；Ollama / llama.cpp 走的是 GGUF 路线，所以本地部署用社区转换的 GGUF 最省事。社区里 bartowski 的档位最全、下载量最高，是稳妥的默认选择。

第二步：创建 Ollama 模型

bash

cat > ~/models/Modelfile <<'EOF'
FROM ./Q4_K_M.gguf

TEMPLATE """{{ if .System }}<|im_start|>system
{{ .System }}<|im_end|>
{{ end }}{{ if .Prompt }}<|im_start|>user
{{ .Prompt }}<|im_end|>
{{ end }}<|im_start|>assistant
"""

PARAMETER num_ctx 8192
PARAMETER temperature 0.7
PARAMETER top_p 0.8
PARAMETER stop "<|im_end|>"
EOF

cd ~/models && ollama create hy4-local -f Modelfile
ollama list

TEMPLATE 必须按模型卡抄

这是本地部署最隐蔽的坑：模型能加载、能出字，但回答质量很差，看起来像模型本身不行。原因几乎都是聊天模板没对上——混元不同代际的模板不完全一样。模板要从对应模型卡的 Usage 段落抄，抄错就重抄。另外 stop 参数也要带上，否则模型会停不下来。

第三步：起服务并验证

bash

# 前台启动（另开终端跑后面的命令）
ollama serve

# 另开一个终端验证原生接口
curl http://127.0.0.1:11434/api/chat -d '{
  "model": "hy4-local",
  "messages": [{"role": "user", "content": "用一句话解释向量数据库"}],
  "stream": false
}'

验证 OpenAI 兼容接口：

bash

# 模型列表
curl http://127.0.0.1:11434/v1/models

# 对话
curl http://127.0.0.1:11434/v1/chat/completions -H 'Content-Type: application/json' -d '{
  "model": "hy4-local",
  "messages": [{"role": "user", "content": "写一个 Python 函数解析 ISO 8601 时间"}]
}'

两个接口的区别

/api/chat 是 Ollama 原生接口，支持 think、images 等扩展字段；/v1/* 是 OpenAI 兼容接口，给第三方工具用。日常接工具只用 /v1，只有需要 Ollama 特有能力（比如传图片给多模态模型）时才用原生接口。

第四步：接进 OpenAI 兼容客户端

python

from openai import OpenAI

client = OpenAI(
    base_url="http://127.0.0.1:11434/v1",
    api_key="ollama",           # 占位，Ollama 不校验
)
resp = client.chat.completions.create(
    model="hy4-local",
    messages=[{"role": "user", "content": "你好"}],
)
print(resp.choices[0].message.content)

第五步：接进具体工具

Dify

在「设置 → 模型供应商 → OpenAI-API-compatible」里填入 API Base URL http://127.0.0.1:11434/v1，API Key 填 ollama，模型名填 hy4-local。注意 Dify 跑在 Docker 里时，127.0.0.1 指向容器本身，要换成宿主机的 IP 或服务名。

Cursor

打开 Cursor 设置里的 Models 区域，添加 OpenAI 提供的模型，Base URL 填本地地址，模型名填 hy4-local。Cursor 对本地端点的支持随版本变化，如果它自动拉取模型列表失败，手动填模型名即可。

Open WebUI

在 Admin Settings → Connections → OpenAI 里填同样的地址，然后到 Models 处把 hy4-local 启用。注意 Open WebUI 的容器网络访问宿主机要用 host.docker.internal 而不是 127.0.0.1。

Continue / Cline 等编辑器插件

在插件的模型配置里选择 OpenAI，填本地 base URL 与模型名。这类插件通常有一个 Local Models 或自定义 provider 选项，选它比改全局设置更干净。

Docker 网络是最常见的翻车点

工具跑在容器里时，localhost 指向的是容器自己。解决办法有两个：把工具的 compose 文件里加上 extra_hosts: ["host.docker.internal:host-gateway"]，然后用 host.docker.internal:11434；或者直接让 Ollama 监听 0.0.0.0:11434（用 OLLAMA_HOST=0.0.0.0 ollama serve），但那样局域网内 anyone 都能访问你的模型，记得同时加访问控制。

第六步：本地与云端并存

很多团队会同时用本地 hy4 和云端模型。做法是给不同工具配不同端点，或者在客户端里做路由：

python

import os

def pick_client(task: str):
    if task in {"classify", "rewrite", "summarize"}:
        return OpenAI(base_url="http://127.0.0.1:11434/v1", api_key="ollama")
    return OpenAI(base_url="https://exaiv.com/api/ai/v1", api_key=os.environ["EXAIV_KEY"])

模型名不要混用

本地模型名是 hy4-local（你自己起的），云端模型 ID 是目录里真实存在的 ID（如 kimi-k3）。在客户端里写错模型名的表现通常是「模型不存在」而不是「连不上」，排查时先确认模型名，再看网络。

故障排查

现象	原因	处理
输出乱码或答非所问	聊天模板不对	按模型卡改 TEMPLATE 与 stop
连接被拒	服务没起，或端口不是 11434	`ollama serve` 后用 curl 验证端口
Docker 里连不上	容器网络隔离	用 host.docker.internal 或监听 0.0.0.0
回答一半被截断	上下文不足或 max_tokens 太小	调大 num_ctx 与 max_tokens
模型名报错	用了云端 ID 或拼错	`ollama list` 看真实名字
首次响应极慢	模型加载进内存	正常现象，后续请求会快很多
显存不够	num_ctx 设太大	调小上下文，KV cache 会线性下降

FAQ

Ollama 和 llama.cpp 怎么选？

要极致性能和参数调节用 llama.cpp；要生态兼容（Open WebUI、Dify、Cursor 等开箱即用）用 Ollama。两者都提供 OpenAI 兼容端点，GGUF 文件可以共用。

Modelfile 里的 TEMPLATE 从哪来？

从对应模型卡的 Usage 段落抄。混元不同代际模板不完全一样，模板错了模型照样能出字但质量崩坏，这是本地部署最常见的误判来源。

Dify 在 Docker 里怎么连本机 Ollama？

容器里的 127.0.0.1 指向容器自己。给 compose 加 extra_hosts 把 host.docker.internal 指向宿主机，然后用这个主机名加 11434 端口作为 Base URL。

可以让 Ollama 对外提供服务吗？

可以，用 OLLAMA_HOST=0.0.0.0 ollama serve 让它监听所有网卡。但 Ollama 默认没有鉴权，局域网内任何人都能调用你的模型，公网暴露前务必加反向代理与访问控制。

混元能通过 EXAIV 云端调用吗？

EXAIV 当前云端目录未接入混元，以模型目录实时列表为准。混元走本地部署这条路径，本文讲的就是把它接进你自己的工具链。

数据来源

仓库清单与档位会随社区更新变化，本文以采样时状态为准。

国产模型一个 Key 调用

EXAIV 已接入 Qwen / DeepSeek / Kimi / GLM 等国产开源模型，OpenAI 兼容端点，注册即用

查看充值套餐

← Back to Integrations

EN ID MS TH TL VI ZH

hy4 Ollama 接入：把本地混元接进 Dify / Cursor / 任意 OpenAI 兼容客户端

30 秒版本

第一步：准备 GGUF 权重

bash

mkdir -p ~/models && cd ~/models
huggingface-cli download bartowski/tencent_Hunyuan-4B-Instruct-GGUF \
  Q4_K_M.gguf --local-dir .
ls -lh

为什么推荐社区 GGUF 而不是官方量化

第二步：创建 Ollama 模型

bash

cat > ~/models/Modelfile <<'EOF'
FROM ./Q4_K_M.gguf

TEMPLATE """{{ if .System }}<|im_start|>system
{{ .System }}<|im_end|>
{{ end }}{{ if .Prompt }}<|im_start|>user
{{ .Prompt }}<|im_end|>
{{ end }}<|im_start|>assistant
"""

PARAMETER num_ctx 8192
PARAMETER temperature 0.7
PARAMETER top_p 0.8
PARAMETER stop "<|im_end|>"
EOF

cd ~/models && ollama create hy4-local -f Modelfile
ollama list

TEMPLATE 必须按模型卡抄

第三步：起服务并验证

bash

# 前台启动（另开终端跑后面的命令）
ollama serve

# 另开一个终端验证原生接口
curl http://127.0.0.1:11434/api/chat -d '{
  "model": "hy4-local",
  "messages": [{"role": "user", "content": "用一句话解释向量数据库"}],
  "stream": false
}'

验证 OpenAI 兼容接口：

bash

# 模型列表
curl http://127.0.0.1:11434/v1/models

# 对话
curl http://127.0.0.1:11434/v1/chat/completions -H 'Content-Type: application/json' -d '{
  "model": "hy4-local",
  "messages": [{"role": "user", "content": "写一个 Python 函数解析 ISO 8601 时间"}]
}'

两个接口的区别

第四步：接进 OpenAI 兼容客户端

python

from openai import OpenAI

client = OpenAI(
    base_url="http://127.0.0.1:11434/v1",
    api_key="ollama",           # 占位，Ollama 不校验
)
resp = client.chat.completions.create(
    model="hy4-local",
    messages=[{"role": "user", "content": "你好"}],
)
print(resp.choices[0].message.content)

第五步：接进具体工具

Dify

Cursor

Open WebUI

Continue / Cline 等编辑器插件

在插件的模型配置里选择 OpenAI，填本地 base URL 与模型名。这类插件通常有一个 Local Models 或自定义 provider 选项，选它比改全局设置更干净。

Docker 网络是最常见的翻车点

第六步：本地与云端并存

很多团队会同时用本地 hy4 和云端模型。做法是给不同工具配不同端点，或者在客户端里做路由：

python

import os

def pick_client(task: str):
    if task in {"classify", "rewrite", "summarize"}:
        return OpenAI(base_url="http://127.0.0.1:11434/v1", api_key="ollama")
    return OpenAI(base_url="https://exaiv.com/api/ai/v1", api_key=os.environ["EXAIV_KEY"])

模型名不要混用

故障排查

现象	原因	处理
输出乱码或答非所问	聊天模板不对	按模型卡改 TEMPLATE 与 stop
连接被拒	服务没起，或端口不是 11434	`ollama serve` 后用 curl 验证端口
Docker 里连不上	容器网络隔离	用 host.docker.internal 或监听 0.0.0.0
回答一半被截断	上下文不足或 max_tokens 太小	调大 num_ctx 与 max_tokens
模型名报错	用了云端 ID 或拼错	`ollama list` 看真实名字
首次响应极慢	模型加载进内存	正常现象，后续请求会快很多
显存不够	num_ctx 设太大	调小上下文，KV cache 会线性下降

FAQ

Ollama 和 llama.cpp 怎么选？

要极致性能和参数调节用 llama.cpp；要生态兼容（Open WebUI、Dify、Cursor 等开箱即用）用 Ollama。两者都提供 OpenAI 兼容端点，GGUF 文件可以共用。

Modelfile 里的 TEMPLATE 从哪来？

从对应模型卡的 Usage 段落抄。混元不同代际模板不完全一样，模板错了模型照样能出字但质量崩坏，这是本地部署最常见的误判来源。

Dify 在 Docker 里怎么连本机 Ollama？

容器里的 127.0.0.1 指向容器自己。给 compose 加 extra_hosts 把 host.docker.internal 指向宿主机，然后用这个主机名加 11434 端口作为 Base URL。

可以让 Ollama 对外提供服务吗？

混元能通过 EXAIV 云端调用吗？

EXAIV 当前云端目录未接入混元，以模型目录实时列表为准。混元走本地部署这条路径，本文讲的就是把它接进你自己的工具链。

数据来源

仓库清单与档位会随社区更新变化，本文以采样时状态为准。

国产模型一个 Key 调用

EXAIV 已接入 Qwen / DeepSeek / Kimi / GLM 等国产开源模型，OpenAI 兼容端点，注册即用

查看充值套餐

← Back to Integrations

hy4 Ollama 接入：把本地混元接进 Dify / Cursor / 任意 OpenAI 兼容客户端

hy4 Ollama 接入：把本地混元接进 Dify / Cursor / 任意 OpenAI 兼容客户端

第一步：准备 GGUF 权重

第二步：创建 Ollama 模型

第三步：起服务并验证

第四步：接进 OpenAI 兼容客户端

第五步：接进具体工具

Dify

Cursor

Open WebUI

Continue / Cline 等编辑器插件

第六步：本地与云端并存

故障排查

FAQ

相关阅读

数据来源

hy4 Ollama 接入：把本地混元接进 Dify / Cursor / 任意 OpenAI 兼容客户端

hy4 Ollama 接入：把本地混元接进 Dify / Cursor / 任意 OpenAI 兼容客户端

第一步：准备 GGUF 权重

第二步：创建 Ollama 模型

第三步：起服务并验证

第四步：接进 OpenAI 兼容客户端

第五步：接进具体工具

Dify

Cursor

Open WebUI

Continue / Cline 等编辑器插件

第六步：本地与云端并存

故障排查

FAQ

相关阅读

数据来源