Cara Menjalankan Model Apa Pun di DeepSeek Harness

DeepSeek Harness (dsh) dilengkapi dengan model-model DeepSeek sendiri yang sudah terpasang, namun Anda tidak terpaku pada mereka. Harness ini memperlakukan penyedia model sebagai konfigurasi: arahkan blok penyedia ke endpoint yang kompatibel dengan OpenAI mana pun, berikan referensi kredensial, dan sesi agen Anda akan berjalan pada model apa pun yang ada di balik URL tersebut. Instance Ollama lokal, gateway perusahaan, Qwen melalui mode kompatibel DashScope, atau penyedia katalog besar seperti Anthropic dan OpenAI, semuanya dapat terhubung ke blok yang sama.

Panduan ini akan membahas blok tersebut secara rinci, lalu membangun tiga resep yang berfungsi: model lokal, endpoint yang di-host dan kompatibel dengan OpenAI, dan penyedia katalog bawaan. Semua yang dikutip di sini berasal dari panduan penyedia resmi di cabang master, diambil pada 20 Agustus 2026. Satu peringatan di awal: dsh adalah pratinjau pengembang, dan README memperingatkan dengan huruf kapital semua bahwa akan ada perubahan yang merusak kompatibilitas. Periksa dokumentasi terhadap versi yang Anda instal sebelum Anda menyalin apa pun ke produksi.

button

Jika Anda baru mengenal harness ini, mulailah dengan apa itu DeepSeek Harness dan cara kerjanya, lalu kembali ke sini untuk konfigurasi penyedianya.

Mengapa perlu mengganti model dalam agent harness

Agent harness adalah sebuah siklus: model merencanakan, memanggil alat, membaca hasil, dan mengulang. Harness memiliki siklus tersebut; model adalah salah satu bahan. Tiga alasan Anda akan mengubah bahan tersebut:

Biaya. Sesi agen menghabiskan token dengan cepat karena setiap hasil alat dimasukkan kembali ke dalam konteks. Mengarahkan sesi rutin ke model yang lebih murah, atau ke DeepSeek V4-Flash daripada V4-Pro, mengubah tagihan Anda tanpa mengubah alur kerja Anda. Anda dapat tetap mengkonfigurasi model "frontier" yang mahal untuk sesi yang membutuhkannya.

Lokalitas data. Beberapa codebase tidak dapat meninggalkan gedung. Blok penyedia yang menunjuk ke model yang berjalan di perangkat keras Anda sendiri berarti prompt, konten file, dan output alat tidak pernah melintasi jaringan. Harness yang sama, UI yang sama, nol egress.

Pengembangan lokal. Saat Anda membangun plugin atau menguji perilaku agen, Anda tidak ingin setiap iterasi menghabiskan kredit API atau bergantung pada jaringan Anda. Model lokal yang kecil cukup cepat untuk menguji siklus, dan Anda dapat menukar model asli kembali saat perilaku menjadi penting.

Desainnya mengikuti arsitektur dsh: segala sesuatu dalam harness adalah plugin, dan adaptor model adalah salah satu bagian yang dapat diganti. Rute penyedia dimiliki oleh plugin dsh-llm-pi-ai, yang didokumentasikan dalam katalog konfigurasi plugin repo sebagai "rute penyedia yang dimiliki instance ini." Itu adalah mekanismenya. Antarmuka yang menghadap pengguna adalah satu blok YAML.

Blok penyedia, kunci per kunci

Penyedia kustom berada di $DSH_HOME/settings.yaml, dan Anda juga dapat membuatnya dari UI web di bawah Pengaturan → Model. Berikut adalah contoh langsung dari dokumentasi resmi:

llm-pi-ai:
  providers:
    my-gateway:
      apiKeyEnv: GATEWAY_API_KEY
      api: openai-completions
      baseURL: https://gateway.example/v1
      models:
        - id: legacy-chat
        - id: vision-preview
          input: [text, image]

Fungsi setiap kunci:

my-gateway adalah ID penyedia. Ini adalah pengenal permanen, jadi pilihlah nama yang bisa Anda gunakan; nama tampilan yang muncul di UI diatur secara terpisah.
apiKeyEnv menamai variabel lingkungan yang menyimpan kunci API Anda. File pengaturan tidak pernah berisi rahasianya sendiri, hanya referensi ini. Lebih lanjut tentang di mana kunci sebenarnya berada di bawah ini.
api mendeklarasikan protokol kawat. openai-completions adalah nilai yang didokumentasikan untuk endpoint yang kompatibel dengan OpenAI, yang membuat janji "model apa pun" berfungsi: sebagian besar gateway, runtime lokal, dan penyedia yang di-host berbicara protokol ini.
baseURL adalah root endpoint tempat harness mengirimkan permintaan.
models mencantumkan ID model yang tersedia melalui penyedia ini. Setiap entri membutuhkan setidaknya sebuah id, yang harus cocok dengan apa yang diharapkan endpoint dalam badan permintaan.
input mendeklarasikan modalitas per model. Model kustom secara default hanya teks, jadi model visi harus secara eksplisit mendeklarasikan input: [text, image] atau lampiran gambar tidak akan mencapainya. Ada juga defaultInput tingkat rute yang menetapkan fallback untuk setiap model dalam penyedia; input tingkat model akan menimpanya.
compat menampung sakelar kompatibilitas untuk endpoint yang menyimpang dari perilaku standar OpenAI. Dokumentasi menyebutkan dua: supportsDeveloperRole: false untuk backend yang menolak peran developer, dan maxTokensField: max_tokens untuk backend yang menginginkan nama bidang batasan output yang lebih lama. Kompatibilitas dapat diatur pada tingkat rute atau per model.

Satu kemudahan yang patut diketahui: saat Anda menambahkan penyedia kustom melalui UI web, opsi "Ambil model yang tersedia" akan menanyakan rute GET /models endpoint yang kompatibel dengan OpenAI dan mengisi daftar model untuk Anda. Jika endpoint Anda mengimplementasikan rute tersebut, Anda tidak perlu mengetik secara manual.

Di mana kunci API sebenarnya disimpan

Rahasia disimpan hanya-tulis di $DSH_HOME/.credentials.yaml. Setelah Anda menyimpan kunci melalui UI, dsh hanya mengembalikan deskriptor yang disunting; nilai literalnya tidak akan pernah ditampilkan lagi. settings.yaml hanya menyimpan referensi (nama apiKeyEnv, deskriptor kredensial), bukan kuncinya sendiri. Pemisahan ini berarti Anda dapat mengkomit atau berbagi file pengaturan tanpa membocorkan apa pun, dan merotasi kunci tanpa menyentuh konfigurasi penyedia.

Resep 1: menjalankan model lokal melalui Ollama

Ollama mengekspos API yang kompatibel dengan OpenAI di http://localhost:11434/v1, yang didokumentasikan Ollama dalam panduan kompatibilitas OpenAI-nya. Karena dsh berbicara openai-completions ke URL dasar mana pun, pasangannya mudah.

[VERIFIKASI: dokumentasi dsh tidak menunjukkan contoh khusus Ollama; resep ini menerapkan skema penyedia kustom yang didokumentasikan ke endpoint Ollama yang kompatibel dengan OpenAI yang didokumentasikan. Uji pada instalasi Anda sebelum menerbitkan secara internal.]

llm-pi-ai:
  providers:
    ollama-local:
      apiKeyEnv: OLLAMA_API_KEY
      api: openai-completions
      baseURL: http://localhost:11434/v1
      models:
        - id: gpt-oss:20b
        - id: qwen3

Catatan tentang ini:

Ollama tidak memerlukan kunci API secara lokal, tetapi skema mengharapkan referensi kredensial, jadi tetapkan nilai dummy: export OLLAMA_API_KEY=ollama. Ollama mengabaikan apa pun yang Anda kirim.
id model harus sesuai dengan tag yang disajikan Ollama. Jalankan ollama list dan salin namanya persis, termasuk tag.
Tarik model terlebih dahulu (ollama pull gpt-oss:20b) dan konfirmasi server merespons sebelum menyambungkannya ke dsh. Kami membahas penyiapan lokal lengkap di cara menjalankan GPT-OSS menggunakan Ollama, dan pola yang sama berfungsi untuk model open-weight lainnya seperti Kimi K3 jika perangkat keras Anda memadai.

Pemeriksaan cepat dapat menyelamatkan Anda dari sesi agen yang membingungkan: akses http://localhost:11434/v1/models di Apidog sebelum menyentuh konfigurasi dsh. Jika permintaan tersebut mengembalikan daftar model Anda, URL dasar sudah benar, server aktif, dan "Ambil model yang tersedia" di UI dsh juga akan berfungsi. Jika tidak, tidak ada konfigurasi harness yang dapat memperbaikinya.

Manajemen ekspektasi: agent harness sangat bergantung pada pemanggilan alat dan konteks yang panjang. Model lokal kecil dapat menangani siklus untuk pengujian, tetapi mereka akan merencanakan dengan lebih buruk dan lebih sering menjatuhkan panggilan alat daripada model "frontier" yang menjadi dasar harness dibangun. Ini baik untuk pengembangan plugin; namun membuat frustrasi untuk pekerjaan nyata.

Resep 2: endpoint kompatibel OpenAI yang di-host (Qwen melalui DashScope)

Untuk contoh yang di-host, pilihlah vendor yang mendokumentasikan kompatibilitas OpenAI-nya daripada yang Anda asumsikan memilikinya. Alibaba Cloud Model Studio (DashScope) melakukannya: halaman kompatibilitas OpenAI-nya mendokumentasikan endpoint /compatible-mode/v1 untuk model Qwen, dengan domain regional spesifik-workspace (untuk Singapura: https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/compatible-mode/v1) dan autentikasi melalui variabel lingkungan DASHSCOPE_API_KEY.

Dipetakan ke skema dsh:

llm-pi-ai:
  providers:
    qwen-dashscope:
      apiKeyEnv: DASHSCOPE_API_KEY
      api: openai-completions
      baseURL: https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/compatible-mode/v1
      models:
        - id: qwen3-max

Ganti {WorkspaceId} dengan domain workspace Anda yang sebenarnya dari konsol Model Studio, dan periksa daftar model vendor untuk ID saat ini; kami menyimpan rangkuman tingkat unggulan di panduan API Qwen 3.8 kami. Pola yang sama berlaku untuk vendor mana pun dengan kompatibilitas OpenAI yang didokumentasikan: API Kimi Moonshot, OpenRouter, deployment vLLM, atau gateway internal perusahaan Anda. Satu-satunya bagian yang berubah adalah baseURL, nama variabel lingkungan, dan ID model. Jika Anda telah mengkonfigurasi model open-source di Codex, ini akan terasa familiar; blok YAML dsh memainkan peran yang sama dengan konfigurasi model_providers Codex.

Dua kekhususan endpoint yang di-host:

Jika endpoint vendor menolak permintaan dengan kesalahan aneh tentang peran atau bidang token, itulah tujuan sakelar compat. Coba supportsDeveloperRole: false terlebih dahulu; implementasi yang kompatibel dengan OpenAI yang lebih lama mendahului peran developer.
Model visi harus mendeklarasikan input: [text, image] secara eksplisit, bahkan jika model yang di-host mendukung gambar. dsh mengasumsikan hanya teks untuk model kustom kecuali jika diberitahu sebaliknya.

Resep 3: penyedia katalog bawaan

Anda tidak memerlukan blok kustom untuk cloud mainstream. dsh menyediakan penyedia katalog untuk DeepSeek, Anthropic, dan OpenAI, di mana pengaturannya sebagian besar adalah "tempel kunci API." Entri katalog khusus membawa alur otentikasi asli mereka sendiri: Bedrock menggunakan kredensial AWS, Vertex menginginkan proyek ADC, Azure membutuhkan versi API-nya, dan Codex mengautentikasi melalui OAuth.

Penyedia katalog adalah jalur dengan sedikit gesekan ketika Anda hanya menginginkan Claude atau GPT di balik harness, dan begitulah cara kebanyakan orang akan menjalankan DeepSeek V4-Pro, yang peluncuran API-nya pada Agustus 2026 tiba bersamaan dengan harness itu sendiri (detail di api-docs.deepseek.com). Penyedia kustom adalah untuk segala sesuatu yang tidak tercakup oleh katalog: runtime lokal, gateway, vendor regional, dan agregator yang kompatibel dengan OpenAI.

Memilih model dan apa yang diingat sesi

Menambahkan penyedia membuat modelnya tersedia; memilih model di Pengaturan → Model menjadikannya default untuk sesi baru. Dua perilaku dari dokumentasi yang patut diingat:

Sesi yang ada mempertahankan model yang mereka mulai. Sesi mencatat model aslinya, sehingga mengubah default di tengah proyek tidak secara diam-diam menulis ulang riwayat atau mengubah apa yang digunakan sesi yang sedang berjalan.
Jika Anda menghapus penyedia yang memiliki default saat ini, komposer akan memblokir input sampai Anda memilih model baru. Harness akan gagal dengan jelas daripada menebak-nebak.

Penetapan sesi itu penting untuk reproduktibilitas: saat Anda membandingkan dsh dengan harness lain (kami melakukan hal itu di DeepSeek Harness vs Claude Code), Anda dapat percaya bahwa transkrip sesi mencerminkan satu model, bukan pertukaran di tengah jalan.

Pemecahan masalah kegagalan umum

baseURL salah atau tidak dapat dijangkau. Kegagalan paling umum adalah yang paling tidak eksotis. Konfirmasikan bahwa URL berakhir di tempat yang diharapkan protokol (biasanya /v1 untuk endpoint yang kompatibel dengan OpenAI, /compatible-mode/v1 untuk DashScope) dan bahwa GET {baseURL}/models biasa berhasil di luar harness. Ini adalah titik pemeriksaan di mana Unduh Apidog membayar dirinya sendiri dalam lima menit: kirim permintaan dengan header yang sama (Authorization: Bearer $KEY) yang akan dikirim oleh harness, dan baca kode status dan badan yang sebenarnya alih-alih kesalahan harness yang dibungkus. Jika Anda mengembangkan secara offline atau vendor tidak stabil, mock respons /models dan /chat/completions penyedia di Apidog dan arahkan baseURL ke mock saat Anda membangun.

Variabel lingkungan hilang atau kosong. apiKeyEnv menamai sebuah variabel; itu tidak membuatnya. Jika variabel tidak diatur dalam lingkungan tempat dsh benar-benar berjalan, permintaan akan keluar tanpa autentikasi dan kembali dengan kode 401. Ingat bahwa proses yang diluncurkan dari GUI atau manajer layanan mungkin tidak mewarisi profil shell Anda. echo $GATEWAY_API_KEY dalam konteks yang sama yang meluncurkan dsh web, bukan hanya di terminal acak.

Ketidakcocokan modalitas input. Anda melampirkan gambar, dan model tidak pernah melihatnya, atau permintaan mengalami kesalahan. Model kustom secara default hanya teks. Tambahkan input: [text, image] pada entri model, atau atur defaultInput pada tingkat rute jika setiap model pada penyedia menangani gambar.

Keanehan protokol. Kesalahan yang menyebutkan peran yang tidak didukung atau parameter token yang ditolak menunjuk pada sakelar kompatibilitas: supportsDeveloperRole: false dan maxTokensField: max_tokens adalah dua yang didokumentasikan.

Semua berfungsi kemarin. Pratinjau pengembang. Kunci versi yang Anda deploy, baca catatan rilis sebelum memutakhirkan, dan harapkan skema pengaturan akan berubah. Repo deepseek-harness adalah sumber kebenaran, bukan postingan blog mana pun, termasuk yang ini.

Satu catatan integrasi lagi: penyedia model hanyalah separuh dari cerita kustomisasi. Separuh lainnya adalah alat apa yang dapat dipanggil oleh agen, dan Anda dapat menyambungkan alur kerja API Anda secara langsung; kami membahasnya dalam menggunakan Apidog CLI di dalam DeepSeek Harness.

Pertanyaan Umum (FAQ)

Apakah DeepSeek Harness secara resmi mendukung Ollama?

Dokumentasi penyedia resmi tidak menyebutkan Ollama secara spesifik. Yang didukungnya adalah setiap endpoint yang berbicara protokol openai-completions, dan Ollama mendokumentasikan API yang kompatibel dengan OpenAI di http://localhost:11434/v1. Resep di atas menggabungkan dua bagian yang didokumentasikan; ujilah pada instalasi Anda, karena dsh adalah pratinjau pengembang dan skema dapat berubah di antara rilis.

Di mana dsh menyimpan kunci API saya?

Di $DSH_HOME/.credentials.yaml, hanya-tulis. UI menampilkan deskriptor yang disunting setelah disimpan, dan settings.yaml hanya memegang referensi seperti nama apiKeyEnv. Anda tidak akan pernah memiliki kunci teks biasa di dalam konfigurasi penyedia Anda.

Bisakah saya menjalankan model yang berbeda untuk sesi yang berbeda?

Ya. Memilih model menetapkan default hanya untuk sesi baru; setiap sesi yang ada mempertahankan model yang digunakannya saat dimulai. Jadi Anda dapat menjalankan model murah seperti DeepSeek V4-Flash untuk sesi rutin, beralih default ke model yang lebih berat untuk masalah yang sulit, dan sesi Anda sebelumnya tetap tidak tersentuh.

Endpoint kustom saya mengembalikan kesalahan yang tidak dihasilkan oleh permintaan yang sama di curl. Bagaimana sekarang?

Bandingkan payload yang persis. Harness mungkin mengirim peran developer atau bidang batas token yang lebih baru yang tidak diterima backend Anda; perbaikan yang didokumentasikan adalah supportsDeveloperRole: false dan maxTokensField: max_tokens di bawah compat. Memutar ulang permintaan berbentuk harness di klien API menunjukkan kepada Anda bidang mana yang membuat backend tersendat.