EN ID MS TH TL VI ZH

Integrasi hy4 dengan Ollama: sambungkan Hunyuan tempatan ke Dify, Cursor dan klien serasi OpenAI

Selepas hy4 berjalan, soalan harian ialah sama ada alat anda boleh memanggilnya. Panduan ini merangkumi import GGUF tempatan ke dalam Ollama melalui Modelfile, menjadikannya perkhidmatan, konfigurasi Dify, Cursor, Open WebUI dan plugin editor, menjalankan tempatan dan cloud serentak, serta halangan yang kerap berlaku.

Integrasi hy4 dengan Ollama: sambungkan Hunyuan tempatan ke Dify, Cursor dan klien serasi OpenAI

Menjalankan hy4 hanya menyelesaikan separuh masalah, kerana yang membentuk pengalaman harian ialah soalan sama ada alat anda boleh memanggilnya. Nilai Ollama terletak pada kemampuannya membawa pengurusan model dan endpoint serasi OpenAI sendiri, jadi Dify, Cursor, Open WebUI dan plugin editor terus memahaminya tanpa kod penyesuai. Artikel ini bergerak peringkat demi peringkat: daripada mengimport GGUF tempatan, menjadikannya perkhidmatan, konfigurasi klien, sehingga menangani masalah.

Ringkasan 30 saat

Import GGUF tempatan ke dalam Ollama dengan ollama create dan sebuah Modelfile, jadikan ia perkhidmatan pada port 11434, kemudian arahkan klien ke http://127.0.0.1:11434/v1 dengan api_key apa saja, dan sahkan melalui senarai model. Dify, Cursor dan Open WebUI kesemuanya bertutur protokol serasi OpenAI, jadi ini kerja konfigurasi dan bukan integrasi yang rumit.

Langkah satu: menyediakan berat GGUF

bash

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

Mengapa menggunakan GGUF komuniti dan bukan quantization rasmi

Versi rasmi ialah FP8, GPTQ-Int4 dan AWQ-Int4, yang memerlukan tindanan pelayan seperti vLLM. Ollama dan llama.cpp bergerak melalui laluan GGUF, jadi penerapan tempatan menggunakan penukaran komuniti ialah jalan terpendek. bartowski mempunyai liputan quantization terluas dan unduhan terbanyak, menjadikannya pilihan lalai yang selamat.

Langkah dua: mencipta model dalam 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 mesti disalin daripada model card

Ini perangkap paling tersembunyi semasa menjalankan tempatan: model dimuatkan, menghasilkan token, tetapi kualiti jawapannya buruk dan nampak seperti model lemah. Punca hampir semuanya ialah templat perbualan yang tidak sepadan, kerana templat Hunyuan berbeza antara generasi. Salin daripada bahagian Usage pada model card yang sepadan. Parameter stop juga mesti ada, jika tidak model tidak akan berhenti.

Langkah tiga: menjadikan perkhidmatan dan pengesahan

bash

# jalankan dalam mod foreground, kemudian buka terminal lain untuk arahan pemeriksaan
ollama serve

# periksa API asal daripada terminal kedua
curl http://127.0.0.1:11434/api/chat -d '{
  "model": "hy4-local",
  "messages": [{"role": "user", "content": "Terangkan pangkalan data vektor dalam satu ayat"}],
  "stream": false
}'

Sahkan permukaan serasi OpenAI:

bash

# senarai model
curl http://127.0.0.1:11434/v1/models

# perbualan
curl http://127.0.0.1:11434/v1/chat/completions -H 'Content-Type: application/json' -d '{
  "model": "hy4-local",
  "messages": [{"role": "user", "content": "Tulis fungsi Python untuk menghurai masa ISO 8601"}]
}'

Dua API, dua tugas berbeza

/api/chat ialah endpoint asal Ollama dan menyokong sambungan seperti think dan images. /v1/* ialah permukaan serasi OpenAI untuk alat pihak ketiga. Semasa menyambung alat, gunakan /v1 sahaja; hanya apabila anda memerlukan keupayaan khusus Ollama, contohnya menghantar gambar kepada model multimodal, barulah gunakan API asal.

Langkah empat: menyambungkan klien serasi OpenAI

python

from openai import OpenAI

client = OpenAI(
    base_url="http://127.0.0.1:11434/v1",
    api_key="ollama",           # nilai placeholder, Ollama tidak mengesahkannya
)
resp = client.chat.completions.create(
    model="hy4-local",
    messages=[{"role": "user", "content": "Hai"}],
)
print(resp.choices[0].message.content)

Langkah lima: menyambungkan alat tertentu

Dify

Dalam Settings, Model Providers, OpenAI-API-compatible, isikan API Base URL http://127.0.0.1:11434/v1, API Key ollama, dan nama model hy4-local. Perhatikan: apabila Dify berjalan dalam Docker, 127.0.0.1 menunjuk kepada container itu sendiri, jadi mesti menggunakan IP atau nama perkhidmatan hos.

Cursor

Buka bahagian Models dalam tetapan Cursor, tambah model melalui pembekal OpenAI, tetapkan Base URL kepada alamat tempatan, dan gunakan hy4-local sebagai nama model. Sokongan endpoint tempatan Cursor berubah mengikut versi, dan mengisi nama model secara manual masih berfungsi apabila penemuan automatik gagal.

Open WebUI

Dalam Admin Settings, Connections, OpenAI, isikan alamat yang sama, kemudian aktifkan hy4-local dalam bahagian Models. Perhatikan bahawa Open WebUI dalam container mesti menghubungi hos melalui host.docker.internal dan bukan 127.0.0.1.

Plugin editor seperti Continue dan Cline

Dalam tetapan model plugin, pilih pembekal OpenAI dan isikan base URL serta nama model tempatan. Kebanyakan plugin ini mempunyai pilihan local models atau custom provider, dan menggunakannya lebih bersih daripada mengubah tetapan global.

Rangkaian Docker ialah tempat paling kerap gagal

Apabila alat berjalan dalam container, localhost menunjuk kepada container itu sendiri. Terdapat dua cara mengendalikannya: menambah extra_hosts: ["host.docker.internal:host-gateway"] pada fail compose kemudian menggunakan host.docker.internal:11434, atau membuat Ollama mendengar 0.0.0.0:11434 dengan OLLAMA_HOST=0.0.0.0 ollama serve. Pilihan kedua menjadikan model anda dapat diakses daripada seluruh rangkaian tempatan, jadi tambahkan kawalan akses sebelum menggunakannya.

Langkah enam: tempatan dan cloud serentak

Banyak pasukan menjalankan hy4 tempatan dan model cloud pada masa yang sama. Caranya ialah memberikan endpoint berbeza kepada alat berbeza, atau menghala dalam klien:

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"])

Jangan menukar nama model

Nama model tempatan ialah hy4-local, yang anda pilih sendiri, manakala ID model cloud ialah ID sebenar yang wujud dalam katalog, contohnya kimi-k3. Salah nama model biasanya gagal dengan "model tidak dijumpai" dan bukan "tidak dapat bersambung", jadi semasa menyahpepijat, periksa nama dahulu, baru rangkaian.

Jadual penanganan masalah

Gejala	Punca	Penanganan
Output pelik atau tidak sepadan soalan	templat perbualan salah	betulkan TEMPLATE dan stop mengikut model card
Sambungan ditolak	perkhidmatan belum berjalan, atau bukan port 11434	jalankan `ollama serve` kemudian periksa port dengan curl
Tidak dapat bersambung dari Docker	pengasingan rangkaian container	gunakan host.docker.internal atau dengarkan 0.0.0.0
Jawapan terpotong di tengah	konteks atau max_tokens terlalu kecil	naikkan num_ctx dan max_tokens
Ralat nama model	menggunakan ID cloud atau salah taip	lihat `ollama list` untuk nama sebenar
Panggilan pertama sangat perlahan	model dimuatkan ke dalam memori	perkara normal, panggilan berikutnya lebih pantas
Memori tidak mencukupi	num_ctx terlalu besar	turunkan konteks, kerana KV cache tumbuh secara linear

FAQ

Adakah patut memilih Ollama atau llama.cpp?

Untuk prestasi maksimum dan parameter yang boleh ditala, llama.cpp. Untuk keserasian ekosistem, kerana Open WebUI, Dify dan Cursor terus berfungsi, Ollama. Kedua-duanya membuka endpoint serasi OpenAI dan boleh berkongsi fail model yang sama.

Di mana mendapatkan TEMPLATE untuk Modelfile?

Daripada bahagian Usage pada model card yang sepadan. Templat Hunyuan berbeza antara generasi, dan templat salah tetap menghasilkan token yang nampak lancar tetapi jawapannya buruk, yang merupakan punca salah diagnosis paling biasa semasa penerapan tempatan.

Bagaimana Dify dalam Docker menghubungi Ollama pada hos?

Dalam container, 127.0.0.1 menunjuk kepada container itu sendiri. Tambahkan extra_hosts yang memetakan host.docker.internal kepada host gateway dalam fail compose, kemudian gunakan nama hos itu dengan port 11434 sebagai Base URL.

Bolehkah Ollama menghidangkan perkhidmatan ke luar?

Boleh, dengan OLLAMA_HOST=0.0.0.0 ollama serve supaya ia mendengar semua antara muka. Tetapi Ollama tiada pengesahan lalai, jadi sesiapa dalam rangkaian boleh memanggil model anda; sebelum membuka kepada rangkaian awam, letakkan reverse proxy dan kawalan akses di hadapan.

Bolehkah Hunyuan dipanggil melalui API EXAIV?

Katalog cloud EXAIV belum membawa Hunyuan; semak direktori model yang aktif. Hunyuan bergerak melalui laluan hosting sendiri, dan artikel ini ialah panduan menyambungkannya ke rantai alat anda.

Bacaan lanjutan

Pemasangan hy4 dengan GGUF — peringkat quantization, pengiraan memori dan arahan llama.cpp
Open WebUI dengan Hunyuan tempatan — konfigurasi antara muka perbualan mandiri
RAG dengan hy4 — menyambung endpoint tempatan ke pangkalan pengetahuan
Integrasi Dify — menyambung model cloud ke Dify
Integrasi Open WebUI — menyambung model cloud ke antara muka mandiri
Panduan pemilihan model hy4 — saiz dan kedudukan A13B

Sumber data

Senarai repositori dan peringkat quantization berubah mengikut kemas kini komuniti; artikel ini mencerminkan keadaan pada masa persampelan.

Satu kunci untuk model sumber terbuka China

EXAIV menyajikan Qwen, DeepSeek, Kimi dan GLM melalui satu endpoint serasi OpenAI. Daftar dan mula memanggil

Lihat pakej kredit

← Back to Integrations

EN ID MS TH TL VI ZH

Integrasi hy4 dengan Ollama: sambungkan Hunyuan tempatan ke Dify, Cursor dan klien serasi OpenAI

Ringkasan 30 saat

Langkah satu: menyediakan berat GGUF

bash

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

Mengapa menggunakan GGUF komuniti dan bukan quantization rasmi

Langkah dua: mencipta model dalam 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 mesti disalin daripada model card

Langkah tiga: menjadikan perkhidmatan dan pengesahan

bash

# jalankan dalam mod foreground, kemudian buka terminal lain untuk arahan pemeriksaan
ollama serve

# periksa API asal daripada terminal kedua
curl http://127.0.0.1:11434/api/chat -d '{
  "model": "hy4-local",
  "messages": [{"role": "user", "content": "Terangkan pangkalan data vektor dalam satu ayat"}],
  "stream": false
}'

Sahkan permukaan serasi OpenAI:

bash

# senarai model
curl http://127.0.0.1:11434/v1/models

# perbualan
curl http://127.0.0.1:11434/v1/chat/completions -H 'Content-Type: application/json' -d '{
  "model": "hy4-local",
  "messages": [{"role": "user", "content": "Tulis fungsi Python untuk menghurai masa ISO 8601"}]
}'

Dua API, dua tugas berbeza

Langkah empat: menyambungkan klien serasi OpenAI

python

from openai import OpenAI

client = OpenAI(
    base_url="http://127.0.0.1:11434/v1",
    api_key="ollama",           # nilai placeholder, Ollama tidak mengesahkannya
)
resp = client.chat.completions.create(
    model="hy4-local",
    messages=[{"role": "user", "content": "Hai"}],
)
print(resp.choices[0].message.content)

Langkah lima: menyambungkan alat tertentu

Dify

Cursor

Open WebUI

Plugin editor seperti Continue dan Cline

Rangkaian Docker ialah tempat paling kerap gagal

Langkah enam: tempatan dan cloud serentak

Banyak pasukan menjalankan hy4 tempatan dan model cloud pada masa yang sama. Caranya ialah memberikan endpoint berbeza kepada alat berbeza, atau menghala dalam klien:

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"])

Jangan menukar nama model

Jadual penanganan masalah

Gejala	Punca	Penanganan
Output pelik atau tidak sepadan soalan	templat perbualan salah	betulkan TEMPLATE dan stop mengikut model card
Sambungan ditolak	perkhidmatan belum berjalan, atau bukan port 11434	jalankan `ollama serve` kemudian periksa port dengan curl
Tidak dapat bersambung dari Docker	pengasingan rangkaian container	gunakan host.docker.internal atau dengarkan 0.0.0.0
Jawapan terpotong di tengah	konteks atau max_tokens terlalu kecil	naikkan num_ctx dan max_tokens
Ralat nama model	menggunakan ID cloud atau salah taip	lihat `ollama list` untuk nama sebenar
Panggilan pertama sangat perlahan	model dimuatkan ke dalam memori	perkara normal, panggilan berikutnya lebih pantas
Memori tidak mencukupi	num_ctx terlalu besar	turunkan konteks, kerana KV cache tumbuh secara linear

FAQ

Adakah patut memilih Ollama atau llama.cpp?

Di mana mendapatkan TEMPLATE untuk Modelfile?

Bagaimana Dify dalam Docker menghubungi Ollama pada hos?

Bolehkah Ollama menghidangkan perkhidmatan ke luar?

Bolehkah Hunyuan dipanggil melalui API EXAIV?

Katalog cloud EXAIV belum membawa Hunyuan; semak direktori model yang aktif. Hunyuan bergerak melalui laluan hosting sendiri, dan artikel ini ialah panduan menyambungkannya ke rantai alat anda.

Bacaan lanjutan

Pemasangan hy4 dengan GGUF — peringkat quantization, pengiraan memori dan arahan llama.cpp
Open WebUI dengan Hunyuan tempatan — konfigurasi antara muka perbualan mandiri
RAG dengan hy4 — menyambung endpoint tempatan ke pangkalan pengetahuan
Integrasi Dify — menyambung model cloud ke Dify
Integrasi Open WebUI — menyambung model cloud ke antara muka mandiri
Panduan pemilihan model hy4 — saiz dan kedudukan A13B

Sumber data

Senarai repositori dan peringkat quantization berubah mengikut kemas kini komuniti; artikel ini mencerminkan keadaan pada masa persampelan.

Satu kunci untuk model sumber terbuka China

EXAIV menyajikan Qwen, DeepSeek, Kimi dan GLM melalui satu endpoint serasi OpenAI. Daftar dan mula memanggil

Lihat pakej kredit

← Back to Integrations