DEV Community

Cover image for Cara Menjalankan Model Apa Pun di DeepSeek Harness
Walse
Walse

Posted on Originally published at apidog.com

Cara Menjalankan Model Apa Pun di DeepSeek Harness

DeepSeek Harness (dsh) dilengkapi dengan model-model DeepSeek yang sudah terpasang, tetapi Anda tidak harus menggunakannya. Penyedia model dikonfigurasi melalui blok YAML: arahkan penyedia ke endpoint yang kompatibel dengan OpenAI, berikan referensi kredensial, lalu jalankan sesi agen dengan model di balik URL tersebut. Anda dapat memakai instance Ollama lokal, gateway perusahaan, Qwen melalui mode kompatibel DashScope, atau penyedia katalog seperti Anthropic dan OpenAI.

Coba Apidog hari ini

Panduan ini menjelaskan struktur blok penyedia dan tiga resep implementasi: model lokal, endpoint yang di-host dan kompatibel dengan OpenAI, serta penyedia katalog bawaan. Seluruh konfigurasi merujuk pada panduan penyedia resmi di cabang master, diambil pada 20 Agustus 2026.

Peringatan: dsh masih merupakan pratinjau pengembang. README memperingatkan adanya perubahan yang dapat merusak kompatibilitas. Selalu cocokkan dokumentasi dengan versi dsh yang Anda instal sebelum menerapkan konfigurasi ke produksi.

Jika Anda baru mengenal harness ini, baca terlebih dahulu apa itu DeepSeek Harness dan cara kerjanya.

Mengapa mengganti model dalam agent harness?

Agent harness menjalankan siklus berikut:

  1. Model membuat rencana.
  2. Agen memanggil alat.
  3. Model membaca hasil alat.
  4. Siklus berulang hingga tugas selesai.

Harness mengelola siklus tersebut, sedangkan model adalah komponen yang dapat diganti. Berikut alasan utama untuk mengganti model.

Biaya

Sesi agen cepat menghabiskan token karena hasil alat terus dimasukkan kembali ke konteks. Gunakan model yang lebih murah untuk pekerjaan rutin, misalnya DeepSeek V4-Flash alih-alih V4-Pro, lalu gunakan model yang lebih kuat hanya untuk tugas yang memerlukannya.

Lokalitas data

Untuk codebase yang tidak boleh meninggalkan jaringan internal, arahkan penyedia ke model yang berjalan di infrastruktur sendiri. Prompt, isi file, dan hasil alat tetap berada di lingkungan lokal tanpa egress jaringan.

Pengembangan lokal

Saat membangun plugin atau menguji perilaku agen, model lokal kecil dapat mempercepat iterasi tanpa menghabiskan kredit API. Setelah alur kerja stabil, ganti kembali ke model produksi untuk validasi akhir.

Arsitektur dsh mendukung pola ini karena semua komponen harness adalah plugin, termasuk adaptor model. Rute penyedia dimiliki oleh plugin dsh-llm-pi-ai, yang dijelaskan dalam katalog konfigurasi plugin sebagai rute penyedia yang dimiliki instance tersebut.

Blok penyedia, kunci per kunci

Penyedia kustom disimpan di:

$DSH_HOME/settings.yaml
Enter fullscreen mode Exit fullscreen mode

Anda juga dapat membuatnya melalui UI web di Pengaturan → Model.

Contoh konfigurasi 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]
Enter fullscreen mode Exit fullscreen mode

Arti setiap kunci:

  • my-gateway: ID penyedia. Gunakan nama yang stabil karena ID ini menjadi pengenal konfigurasi.
  • apiKeyEnv: nama variabel lingkungan yang menyimpan API key. Jangan masukkan rahasia langsung ke settings.yaml.
  • api: protokol API yang digunakan. Untuk endpoint kompatibel OpenAI, gunakan openai-completions.
  • baseURL: root URL endpoint tujuan.
  • models: daftar model yang tersedia pada penyedia tersebut.
  • id: ID model yang harus sama dengan ID yang diharapkan endpoint API.
  • input: modalitas input model. Model kustom dianggap hanya mendukung teks secara default. Untuk model visi, tambahkan input: [text, image].
  • defaultInput: fallback modalitas untuk semua model dalam satu penyedia. Nilai input pada model akan menimpa nilai ini.
  • compat: pengaturan kompatibilitas untuk endpoint yang tidak sepenuhnya mengikuti perilaku standar OpenAI.

Contoh compat:

compat:
  supportsDeveloperRole: false
  maxTokensField: max_tokens
Enter fullscreen mode Exit fullscreen mode

Gunakan:

  • supportsDeveloperRole: false jika backend menolak peran developer.
  • maxTokensField: max_tokens jika backend mengharapkan nama field batas token lama.

Konfigurasi compat dapat diterapkan pada tingkat penyedia atau per model.

Jika menambahkan penyedia melalui UI web, gunakan opsi Ambil model yang tersedia. dsh akan memanggil endpoint GET /models untuk mengisi daftar model secara otomatis, selama endpoint Anda mendukung rute tersebut.

Di mana API key disimpan?

Rahasia disimpan hanya-tulis di:

$DSH_HOME/.credentials.yaml
Enter fullscreen mode Exit fullscreen mode

Setelah API key disimpan melalui UI, dsh hanya menampilkan deskriptor yang disunting. Nilai kunci literal tidak ditampilkan kembali.

Dengan pola ini:

  • settings.yaml hanya menyimpan referensi seperti apiKeyEnv.
  • API key dapat dirotasi tanpa mengubah konfigurasi penyedia.
  • Konfigurasi dapat dibagikan atau dikomit tanpa memasukkan rahasia.

Resep 1: menjalankan model lokal melalui Ollama

Ollama menyediakan API yang kompatibel dengan OpenAI pada:

http://localhost:11434/v1
Enter fullscreen mode Exit fullscreen mode

Lihat panduan kompatibilitas OpenAI Ollama untuk detail endpoint.

Konfigurasikan Ollama sebagai penyedia dsh:

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
Enter fullscreen mode Exit fullscreen mode

Langkah implementasi:

  1. Jalankan Ollama.
  2. Tarik model yang diperlukan.
  3. Tetapkan variabel lingkungan dummy.
  4. Tambahkan konfigurasi penyedia.
  5. Verifikasi endpoint sebelum membuka dsh.

Contoh:

ollama pull gpt-oss:20b
export OLLAMA_API_KEY=ollama
ollama list
Enter fullscreen mode Exit fullscreen mode

Ollama lokal tidak memerlukan API key, tetapi skema penyedia dsh tetap membutuhkan referensi apiKeyEnv. Nilai dummy seperti ollama cukup karena Ollama mengabaikan nilai tersebut.

Pastikan nilai id model sama persis dengan tag dari ollama list, termasuk versinya.

Untuk panduan penyiapan model lokal, lihat cara menjalankan GPT-OSS menggunakan Ollama.

Sebelum menghubungkan Ollama ke dsh, uji endpoint berikut:

GET http://localhost:11434/v1/models
Enter fullscreen mode Exit fullscreen mode

Gunakan Apidog untuk memastikan server aktif, URL benar, dan daftar model tersedia. Jika endpoint ini gagal, masalahnya berada di runtime Ollama atau jaringan lokal, bukan di konfigurasi dsh.

Catatan: dokumentasi dsh tidak memberikan contoh Ollama secara spesifik. Konfigurasi ini menerapkan skema penyedia kustom dsh ke endpoint kompatibel OpenAI yang didokumentasikan Ollama. Uji pada instalasi Anda sebelum dipakai secara internal atau di produksi.

Model lokal kecil dapat memadai untuk menguji siklus agen, plugin, dan pemanggilan alat. Namun, model tersebut dapat lebih lemah dalam perencanaan, konteks panjang, dan pemanggilan alat dibandingkan model frontier.

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

Untuk penyedia yang di-host, gunakan vendor yang mendokumentasikan kompatibilitas OpenAI secara eksplisit.

Alibaba Cloud Model Studio (DashScope) mendokumentasikan endpoint kompatibel OpenAI pada path:

/compatible-mode/v1
Enter fullscreen mode Exit fullscreen mode

Untuk region Singapura, format endpointnya adalah:

https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/compatible-mode/v1
Enter fullscreen mode Exit fullscreen mode

Lihat dokumentasi kompatibilitas OpenAI DashScope.

Konfigurasi 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
Enter fullscreen mode Exit fullscreen mode

Ganti {WorkspaceId} dengan domain workspace dari konsol Model Studio. Periksa dokumentasi vendor untuk ID model terbaru. Anda juga dapat merujuk panduan API Qwen 3.8.

Pola ini juga berlaku untuk:

  • Moonshot Kimi API
  • OpenRouter
  • deployment vLLM
  • gateway internal perusahaan
  • penyedia lain dengan endpoint kompatibel OpenAI

Biasanya hanya tiga bagian yang berubah:

apiKeyEnv: NAMA_VARIABEL_API_KEY
baseURL: https://endpoint-anda/v1
models:
  - id: model-id-anda
Enter fullscreen mode Exit fullscreen mode

Jika sebelumnya Anda pernah mengonfigurasi model open-source di Codex, polanya serupa: blok YAML dsh berperan seperti konfigurasi model_providers di Codex.

Menangani perbedaan endpoint yang di-host

Jika endpoint vendor menolak request terkait peran atau parameter token, tambahkan konfigurasi kompatibilitas:

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
      compat:
        supportsDeveloperRole: false
        maxTokensField: max_tokens
      models:
        - id: qwen3-max
Enter fullscreen mode Exit fullscreen mode

Untuk model visi, deklarasikan modalitas secara eksplisit:

models:
  - id: model-vision
    input: [text, image]
Enter fullscreen mode Exit fullscreen mode

Tanpa input: [text, image], dsh akan memperlakukan model kustom sebagai model teks saja.

Resep 3: penyedia katalog bawaan

Anda tidak perlu membuat blok penyedia kustom untuk cloud mainstream. dsh menyediakan penyedia katalog untuk:

  • DeepSeek
  • Anthropic
  • OpenAI

Untuk sebagian besar kasus, konfigurasi penyedia katalog cukup dengan memasukkan API key melalui UI.

Beberapa penyedia memiliki alur autentikasi khusus:

  • Bedrock menggunakan kredensial AWS.
  • Vertex menggunakan proyek ADC.
  • Azure membutuhkan versi API.
  • Codex menggunakan OAuth.

Gunakan penyedia katalog jika Anda hanya membutuhkan Claude, GPT, atau model DeepSeek melalui harness. Penyedia kustom lebih cocok untuk runtime lokal, gateway, vendor regional, agregator, dan endpoint OpenAI-compatible lainnya.

Untuk detail API DeepSeek, lihat api-docs.deepseek.com.

Memilih model dan perilaku sesi

Menambahkan penyedia hanya membuat model tersedia. Untuk menjadikannya default, pilih model melalui Pengaturan → Model.

Dua perilaku penting:

  1. Sesi yang sudah ada tetap memakai model awalnya.

    Mengubah model default tidak mengubah model pada sesi yang sedang berjalan atau riwayat sesi sebelumnya.

  2. Menghapus penyedia default akan memblokir composer.

    Anda harus memilih model baru sebelum melanjutkan. dsh tidak akan menebak model pengganti.

Perilaku ini membantu reproduktibilitas. Saat membandingkan dsh dengan harness lain, misalnya dalam DeepSeek Harness vs Claude Code, transkrip sesi tetap merepresentasikan satu model yang konsisten.

Pemecahan masalah kegagalan umum

baseURL salah atau tidak dapat dijangkau

Pastikan URL menggunakan path yang benar:

  • Endpoint OpenAI-compatible biasanya berakhir dengan /v1.
  • DashScope menggunakan /compatible-mode/v1.

Uji endpoint di luar harness:

GET {baseURL}/models
Enter fullscreen mode Exit fullscreen mode

Gunakan Unduh Apidog untuk mengirim request dengan header yang sama seperti dsh:

Authorization: Bearer $KEY
Enter fullscreen mode Exit fullscreen mode

Periksa kode status dan body respons secara langsung. Jika Anda sedang bekerja offline atau vendor tidak stabil, mock endpoint berikut lalu arahkan baseURL dsh ke mock tersebut:

GET /models
POST /chat/completions
Enter fullscreen mode Exit fullscreen mode

Variabel lingkungan hilang atau kosong

apiKeyEnv hanya menyebut nama variabel; konfigurasi ini tidak membuat variabel tersebut.

Contoh:

apiKeyEnv: GATEWAY_API_KEY
Enter fullscreen mode Exit fullscreen mode

Pastikan nilainya tersedia pada proses yang menjalankan dsh:

echo $GATEWAY_API_KEY
Enter fullscreen mode Exit fullscreen mode

Jalankan pengecekan dalam konteks yang sama dengan proses dsh web. Proses yang dimulai dari GUI atau service manager mungkin tidak mewarisi profil shell Anda.

Jika variabel tidak tersedia, request dapat dikirim tanpa autentikasi dan menghasilkan respons 401.

Ketidakcocokan modalitas input

Jika gambar dilampirkan tetapi tidak sampai ke model, atau request gagal, deklarasikan kemampuan input model:

models:
  - id: model-vision
    input: [text, image]
Enter fullscreen mode Exit fullscreen mode

Jika semua model pada penyedia mendukung gambar, gunakan fallback pada tingkat penyedia:

defaultInput: [text, image]
Enter fullscreen mode Exit fullscreen mode

Keanehan protokol

Jika error menyebut peran yang tidak didukung atau parameter token yang ditolak, gunakan compat:

compat:
  supportsDeveloperRole: false
  maxTokensField: max_tokens
Enter fullscreen mode Exit fullscreen mode

Konfigurasi yang sebelumnya berfungsi kini gagal

dsh adalah pratinjau pengembang. Kunci versi yang Anda deploy, baca catatan rilis sebelum upgrade, dan anggap skema konfigurasi dapat berubah.

Repo deepseek-harness adalah sumber kebenaran untuk konfigurasi terbaru, bukan postingan blog ini.

Penyedia model hanya setengah dari kustomisasi agen. Setengah lainnya adalah alat yang dapat dipanggil agen. Untuk menghubungkan workflow API ke harness, lihat menggunakan Apidog CLI di dalam DeepSeek Harness.

Pertanyaan Umum (FAQ)

Apakah DeepSeek Harness secara resmi mendukung Ollama?

Dokumentasi penyedia resmi tidak menyebut Ollama secara spesifik. Namun, dsh mendukung endpoint yang menggunakan protokol openai-completions, sedangkan Ollama mendokumentasikan API kompatibel OpenAI di:

http://localhost:11434/v1
Enter fullscreen mode Exit fullscreen mode

Resep Ollama di atas menggabungkan dua bagian yang didokumentasikan tersebut. Uji pada instalasi Anda karena dsh masih merupakan pratinjau pengembang dan skemanya dapat berubah antar-rilis.

Di mana dsh menyimpan API key saya?

dsh menyimpan API key di:

$DSH_HOME/.credentials.yaml
Enter fullscreen mode Exit fullscreen mode

File ini bersifat hanya-tulis. UI hanya menampilkan deskriptor yang disunting setelah penyimpanan, sedangkan settings.yaml menyimpan referensi seperti apiKeyEnv, bukan nilai API key mentah.

Bisakah saya menggunakan model berbeda untuk sesi berbeda?

Ya. Pemilihan model menentukan default untuk sesi baru saja. Setiap sesi yang sudah ada tetap memakai model yang digunakan saat sesi dimulai.

Misalnya, gunakan DeepSeek V4-Flash untuk sesi rutin, lalu ubah default ke model yang lebih kuat untuk masalah kompleks. Sesi lama tidak akan berubah.

Endpoint kustom saya gagal di dsh, tetapi berhasil dengan curl. Apa yang harus diperiksa?

Bandingkan payload request secara persis. Harness mungkin mengirim:

  • peran developer, atau
  • field batas token yang lebih baru.

Jika backend tidak mendukungnya, tambahkan:

compat:
  supportsDeveloperRole: false
  maxTokensField: max_tokens
Enter fullscreen mode Exit fullscreen mode

Putar ulang request yang dibentuk oleh harness menggunakan klien API untuk mengidentifikasi field yang ditolak backend.

Top comments (0)