EN ID MS TH TL VI ZH

Integrasi hy4 dengan Ollama: menghubungkan Hunyuan lokal ke Dify, Cursor, dan klien kompatibel OpenAI

Setelah hy4 berjalan, pertanyaan harian adalah apakah alat Anda bisa memanggilnya. Panduan ini mencakup mengimpor GGUF lokal ke Ollama lewat Modelfile, menyalakannya, mengonfigurasi Dify, Cursor, Open WebUI dan plugin editor, menjalankan lokal dan cloud berdampingan, serta hambatan yang biasa muncul.

Integrasi hy4 dengan Ollama: menghubungkan Hunyuan lokal ke Dify, Cursor, dan klien kompatibel OpenAI

Menjalankan hy4 hanya menyelesaikan separuh masalah, karena yang membentuk pengalaman harian adalah pertanyaan apakah alat Anda bisa memanggilnya. Nilai Ollama terletak pada kemampuannya membawa manajemen model dan endpoint kompatibel OpenAI sendiri, sehingga Dify, Cursor, Open WebUI, dan plugin editor langsung memahaminya tanpa perlu kode adaptasi. Artikel ini berjalan tahap demi tahap: dari mengimpor GGUF lokal, menyalakannya, mengonfigurasi klien, hingga menangani masalah.

Ringkasan 30 detik

Impor GGUF lokal ke Ollama dengan ollama create dan sebuah Modelfile, sajikan di port 11434, lalu arahkan klien ke http://127.0.0.1:11434/v1 dengan api_key apa pun, dan verifikasi lewat daftar model. Dify, Cursor, dan Open WebUI semuanya berbicara protokol kompatibel OpenAI, jadi ini pekerjaan konfigurasi, bukan integrasi.

Langkah satu: menyiapkan bobot 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 memakai GGUF komunitas, bukan kuantisasi resmi

Versi resmi adalah FP8, GPTQ-Int4, dan AWQ-Int4, yang membutuhkan tumpukan peladen seperti vLLM. Ollama dan llama.cpp berjalan lewat jalur GGUF, jadi penerapan lokal memakai konversi komunitas adalah jalan terpendek. bartowski memiliki cakupan quantization terluas dan unduhan terbanyak, sehingga menjadi pilihan bawaan yang aman.

Langkah dua: membuat model di 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 harus disalin dari model card

Ini jebakan paling tersembunyi saat menjalankan lokal: model termuat, menghasilkan token, tetapi kualitas jawabannya buruk dan tampak seperti model lemah. Penyebabnya hampir selalu templat percakapan yang tidak cocok, karena templat Hunyuan berbeda antar generasi. Salin dari bagian Usage pada model card yang sesuai. Parameter stop juga wajib ada, kalau tidak model tidak akan berhenti.

Langkah tiga: menyajikan dan memverifikasi

bash

# jalankan di foreground, lalu buka terminal lain untuk perintah pemeriksaan
ollama serve

# periksa API asli dari terminal kedua
curl http://127.0.0.1:11434/api/chat -d '{
  "model": "hy4-local",
  "messages": [{"role": "user", "content": "Jelaskan basis data vektor dalam satu kalimat"}],
  "stream": false
}'

Verifikasi permukaan kompatibel OpenAI:

bash

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

# percakapan
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 mengurai waktu ISO 8601"}]
}'

Dua API, dua pekerjaan berbeda

/api/chat adalah endpoint asli Ollama dan mendukung ekstensi seperti think dan images. /v1/* adalah permukaan kompatibel OpenAI untuk alat pihak ketiga. Saat menghubungkan alat, cukup gunakan /v1; hanya ketika Anda membutuhkan kemampuan khusus Ollama, misalnya mengirim gambar ke model multimodal, barulah pakai API asli.

Langkah empat: menghubungkan klien kompatibel OpenAI

python

from openai import OpenAI

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

Langkah lima: menghubungkan alat tertentu

Dify

Di Settings, Model Providers, OpenAI-API-compatible, isi API Base URL http://127.0.0.1:11434/v1, API Key ollama, dan nama model hy4-local. Perhatikan: saat Dify berjalan di Docker, 127.0.0.1 menunjuk ke container itu sendiri, jadi harus memakai IP atau nama layanan host.

Cursor

Buka bagian Models di pengaturan Cursor, tambahkan model lewat penyedia OpenAI, atur Base URL ke alamat lokal, dan pakai hy4-local sebagai nama model. Dukungan endpoint lokal Cursor berubah mengikuti versi, dan mengisi nama model secara manual tetap berfungsi bila penemuan otomatis gagal.

Open WebUI

Di Admin Settings, Connections, OpenAI, isi alamat yang sama, lalu aktifkan hy4-local di bagian Models. Perhatikan bahwa Open WebUI di dalam container harus menghubungi host lewat host.docker.internal bukan 127.0.0.1.

Plugin editor seperti Continue dan Cline

Di pengaturan model plugin, pilih penyedia OpenAI dan isi base URL serta nama model lokal. Kebanyakan plugin ini punya opsi local models atau custom provider, dan memakainya lebih bersih daripada mengubah pengaturan global.

Jaringan Docker adalah tempat paling sering gagal

Saat alat berjalan di dalam container, localhost menunjuk ke container itu sendiri. Ada dua cara menanganinya: menambahkan extra_hosts: ["host.docker.internal:host-gateway"] pada berkas compose lalu memakai host.docker.internal:11434, atau membuat Ollama mendengarkan 0.0.0.0:11434 dengan OLLAMA_HOST=0.0.0.0 ollama serve. Pilihan kedua membuat model Anda dapat diakses dari seluruh jaringan lokal, jadi tambahkan kontrol akses sebelum memakainya.

Langkah enam: lokal dan cloud berdampingan

Banyak tim menjalankan hy4 lokal dan model cloud pada saat bersamaan. Caranya adalah memberikan endpoint berbeda untuk alat yang berbeda, atau routing di 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 lokal adalah hy4-local, yang Anda pilih sendiri, sementara ID model cloud adalah ID nyata yang ada di katalog, misalnya kimi-k3. Salah nama model biasanya gagal dengan "model tidak ditemukan" dan bukan "tidak dapat terhubung", jadi saat menelusuri masalah, periksa nama lebih dulu, baru jaringan.

Tabel penanganan masalah

Gejala	Penyebab	Penanganan
Keluaran aneh atau tidak sesuai pertanyaan	templat percakapan salah	perbaiki TEMPLATE dan stop sesuai model card
Koneksi ditolak	layanan belum berjalan, atau bukan port 11434	jalankan `ollama serve` lalu periksa port dengan curl
Tidak terhubung dari Docker	isolasi jaringan container	pakai host.docker.internal atau dengarkan 0.0.0.0
Jawaban terpotong di tengah	konteks atau max_tokens terlalu kecil	naikkan num_ctx dan max_tokens
Galat nama model	memakai ID cloud atau salah ketik	lihat `ollama list` untuk nama sebenarnya
Panggilan pertama sangat lambat	model dimuat ke memori	hal yang normal, panggilan berikutnya lebih cepat
Memori tidak cukup	num_ctx terlalu besar	turunkan konteks, karena KV cache tumbuh secara linear

FAQ

Haruskah memilih Ollama atau llama.cpp?

Untuk kinerja maksimal dan parameter yang dapat diatur, llama.cpp. Untuk kompatibilitas ekosistem, karena Open WebUI, Dify, dan Cursor langsung berfungsi, Ollama. Keduanya membuka endpoint kompatibel OpenAI dan bisa berbagi berkas model yang sama.

Di mana mendapat TEMPLATE untuk Modelfile?

Dari bagian Usage pada model card yang sesuai. Templat Hunyuan berbeda antar generasi, dan templat salah tetap menghasilkan token yang terlihat lancar tetapi jawabannya buruk, yang merupakan sumber misdiagnosis paling umum saat penerapan lokal.

Bagaimana Dify di Docker menghubungi Ollama di host?

Di dalam container, 127.0.0.1 menunjuk ke container itu sendiri. Tambahkan extra_hosts yang memetakan host.docker.internal ke host gateway pada berkas compose, lalu gunakan nama host itu dengan port 11434 sebagai Base URL.

Bisakah Ollama disajikan ke luar?

Bisa, dengan OLLAMA_HOST=0.0.0.0 ollama serve agar mendengarkan semua antarmuka. Tetapi Ollama tidak memiliki autentikasi bawaan, sehingga siapa pun di jaringan dapat memanggil model Anda; sebelum membuka ke jaringan publik, letakkan reverse proxy dan kontrol akses di depan.

Bisakah Hunyuan dipanggil lewat API EXAIV?

Katalog cloud EXAIV belum memuat Hunyuan; periksa direktori model yang aktif. Hunyuan berjalan lewat jalur hosting sendiri, dan artikel ini adalah panduan menghubungkannya ke rantai alat Anda.

Bacaan lanjutan

Penerapan hy4 dengan GGUF — tingkat quantization, perhitungan memori, dan perintah llama.cpp
Open WebUI dengan Hunyuan lokal — konfigurasi antarmuka percakapan mandiri
RAG dengan hy4 — menghubungkan endpoint lokal ke basis pengetahuan
Integrasi Dify — menghubungkan model cloud ke Dify
Integrasi Open WebUI — menghubungkan model cloud ke antarmuka mandiri
Panduan pemilihan model hy4 — ukuran dan posisi A13B

Sumber data

Daftar repositori dan tingkat quantization berubah mengikuti pembaruan komunitas; artikel ini mencerminkan keadaan saat pengambilan sampel.

Satu kunci untuk model open-bobot Tiongkok

EXAIV menyajikan Qwen, DeepSeek, Kimi dan GLM lewat satu endpoint yang kompatibel dengan OpenAI. Daftar lalu langsung panggil

Lihat paket kredit

← Back to Integrations

EN ID MS TH TL VI ZH

Integrasi hy4 dengan Ollama: menghubungkan Hunyuan lokal ke Dify, Cursor, dan klien kompatibel OpenAI

Ringkasan 30 detik

Langkah satu: menyiapkan bobot 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 memakai GGUF komunitas, bukan kuantisasi resmi

Langkah dua: membuat model di 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 harus disalin dari model card

Langkah tiga: menyajikan dan memverifikasi

bash

# jalankan di foreground, lalu buka terminal lain untuk perintah pemeriksaan
ollama serve

# periksa API asli dari terminal kedua
curl http://127.0.0.1:11434/api/chat -d '{
  "model": "hy4-local",
  "messages": [{"role": "user", "content": "Jelaskan basis data vektor dalam satu kalimat"}],
  "stream": false
}'

Verifikasi permukaan kompatibel OpenAI:

bash

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

# percakapan
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 mengurai waktu ISO 8601"}]
}'

Dua API, dua pekerjaan berbeda

Langkah empat: menghubungkan klien kompatibel OpenAI

python

from openai import OpenAI

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

Langkah lima: menghubungkan alat tertentu

Dify

Cursor

Open WebUI

Plugin editor seperti Continue dan Cline

Jaringan Docker adalah tempat paling sering gagal

Langkah enam: lokal dan cloud berdampingan

Banyak tim menjalankan hy4 lokal dan model cloud pada saat bersamaan. Caranya adalah memberikan endpoint berbeda untuk alat yang berbeda, atau routing di 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

Tabel penanganan masalah

Gejala	Penyebab	Penanganan
Keluaran aneh atau tidak sesuai pertanyaan	templat percakapan salah	perbaiki TEMPLATE dan stop sesuai model card
Koneksi ditolak	layanan belum berjalan, atau bukan port 11434	jalankan `ollama serve` lalu periksa port dengan curl
Tidak terhubung dari Docker	isolasi jaringan container	pakai host.docker.internal atau dengarkan 0.0.0.0
Jawaban terpotong di tengah	konteks atau max_tokens terlalu kecil	naikkan num_ctx dan max_tokens
Galat nama model	memakai ID cloud atau salah ketik	lihat `ollama list` untuk nama sebenarnya
Panggilan pertama sangat lambat	model dimuat ke memori	hal yang normal, panggilan berikutnya lebih cepat
Memori tidak cukup	num_ctx terlalu besar	turunkan konteks, karena KV cache tumbuh secara linear

FAQ

Haruskah memilih Ollama atau llama.cpp?

Di mana mendapat TEMPLATE untuk Modelfile?

Bagaimana Dify di Docker menghubungi Ollama di host?

Bisakah Ollama disajikan ke luar?

Bisakah Hunyuan dipanggil lewat API EXAIV?

Katalog cloud EXAIV belum memuat Hunyuan; periksa direktori model yang aktif. Hunyuan berjalan lewat jalur hosting sendiri, dan artikel ini adalah panduan menghubungkannya ke rantai alat Anda.

Bacaan lanjutan

Penerapan hy4 dengan GGUF — tingkat quantization, perhitungan memori, dan perintah llama.cpp
Open WebUI dengan Hunyuan lokal — konfigurasi antarmuka percakapan mandiri
RAG dengan hy4 — menghubungkan endpoint lokal ke basis pengetahuan
Integrasi Dify — menghubungkan model cloud ke Dify
Integrasi Open WebUI — menghubungkan model cloud ke antarmuka mandiri
Panduan pemilihan model hy4 — ukuran dan posisi A13B

Sumber data

Daftar repositori dan tingkat quantization berubah mengikuti pembaruan komunitas; artikel ini mencerminkan keadaan saat pengambilan sampel.

Satu kunci untuk model open-bobot Tiongkok

EXAIV menyajikan Qwen, DeepSeek, Kimi dan GLM lewat satu endpoint yang kompatibel dengan OpenAI. Daftar lalu langsung panggil

Lihat paket kredit

← Back to Integrations