Ringkasan: DeepSeek Harness dapat terhubung ke gateway seperti APIYI melalui “API model kustom”. Pengembang mengonfigurasi penyedia secara terpisah untuk setiap protokol, mengisi ID model yang benar-benar didukung oleh gateway, dan menghubungkan alat pencarian web secara terpisah sesuai kebutuhan tugas.
DeepSeek Harness mendukung penambahan gateway API pihak ketiga sebagai penyedia model kustom, dengan empat protokol pilihan: OpenAI Chat Completions, OpenAI Responses, Anthropic Messages, dan Gemini API. Dengan demikian, satu instans Harness dapat memanggil model dari beberapa vendor sekaligus melalui gateway terpadu seperti APIYI apiyi.com. Keberhasilan integrasi bergantung pada empat hal: kesesuaian protokol dengan Base URL, kesesuaian ID model dengan gateway, kompatibilitas parameter penalaran dan output, serta perencanaan alat pencarian web secara terpisah.
Artikel berikut pertama-tama menjelaskan mekanisme adaptasi model Harness dan posisi gateway di dalamnya, lalu menyelesaikan satu konfigurasi penyedia kustom item demi item melalui antarmuka pengaturan, sekaligus memberikan templat berkas konfigurasi APIYI. Selanjutnya, artikel merangkum masalah kompatibilitas dan kode kesalahan yang paling umum ketika antarmuka dapat terhubung tetapi pemanggilan gagal, membedakan dua jalur pencarian web—pencarian bawaan server DeepSeek serta Search / Fetch mandiri APIYI—dan pada akhirnya memberikan desain berlapis serta saran penerapan untuk Agent multi-model.

Yang Perlu Diketahui: Terminologi Integrasi Multi-Model DeepSeek Harness
| Istilah | Penjelasan |
|---|---|
| Harness | Kerangka kerja operasi Agent, bertanggung jawab atas integrasi model, pemanggilan tool, konteks, sesi, dan siklus eksekusi tugas |
| API Gateway | Gateway yang secara terpusat meneruskan dan mengelola beberapa permintaan API model, serta menyediakan satu titik masuk ke luar |
| Base URL | Alamat dasar permintaan API; protokol yang berbeda memiliki prefiks jalur alamat yang berbeda |
| Provider | Penyedia layanan model yang dikonfigurasi di Harness, sesuai dengan satu set alamat, protokol, dan kunci |
| Model ID | Pengenal model yang ditentukan dalam permintaan; harus konsisten dengan nama yang benar-benar disediakan oleh gateway |
| Chat Completions | Antarmuka completion percakapan bergaya OpenAI; protokol yang paling umum digunakan oleh gateway kompatibel |
| Responses API | Antarmuka respons terstruktur OpenAI, ditujukan untuk pemanggilan tool dan interaksi multi-turn |
| Anthropic Messages | Antarmuka pesan bergaya Anthropic, protokol native untuk model seri Claude |
| Reasoning Effort | Parameter tingkat upaya penalaran model, seperti off, low, medium, high, max |
| Tool Calling | Model atau Agent memutuskan untuk memanggil tool eksternal dan menggunakan hasilnya untuk penalaran berikutnya |
| Search / Fetch | Search bertanggung jawab melakukan pencarian web dan mengembalikan daftar hasil; Fetch bertanggung jawab mengambil isi halaman web yang ditentukan |
| API Key | Kredensial autentikasi identitas, menentukan model dan antarmuka mana yang dapat diakses oleh permintaan |
1 Mengapa DeepSeek Harness Cocok untuk Integrasi API Multi-Model
1.1 Mekanisme Penyedia Model di DeepSeek Harness
DeepSeek Harness dirilis sebagai sumber terbuka pada 13 Agustus 2026 dalam versi pratinjau pengembang dengan lisensi MIT. Arsitektur intinya adalah “Everything is a Plugin”. Adaptor model, alat, Skills, penyimpanan, dan manajemen sesi semuanya merupakan plugin yang dapat diganti. Karena itu, integrasi model menjadi item konfigurasi yang terbuka, bukan keterikatan vendor yang ditanam mati di dalam produk.
Pada lapisan model, Harness memungkinkan pengguna menambahkan beberapa penyedia dan berganti model dalam sesi. Setiap penyedia dapat dikonfigurasi dengan kunci API, Base URL, nama model, protokol API, panjang konteks, Token keluaran maksimum, kemampuan input gambar, dan tingkat penalaran. Layanan proksi API, gateway internal perusahaan, dan layanan model mandiri semuanya dapat terhubung sebagai penyedia terpisah.
Perlu dicatat, Harness masih berada pada tahap pratinjau pengembang. Tim resmi mengingatkan bahwa versi mendatang dapat membawa perubahan yang merusak. Sebelum digunakan di lingkungan produksi, sebaiknya kunci versi dan cadangkan konfigurasi.
1.2 Peran Gateway API di DeepSeek Harness
Dalam pandangan Harness, gateway adalah sebuah Provider. Empat field menentukan arah sebuah permintaan: Base URL menunjuk ke alamat gateway, protokol menentukan format permintaan dan respons, kunci API membuktikan identitas pemanggil, dan Model ID memberi tahu gateway model mana yang harus menerima permintaan yang diteruskan.
Sebagai contoh, platform APIYI apiyi.com menyediakan model OpenAI, Claude, Gemini, DeepSeek, dan lainnya melalui satu kunci API, serta membuka tiga titik masuk protokol: kompatibel OpenAI, native Anthropic, dan Gemini. Di Harness, cukup membuat penyedia yang sesuai dengan protokol tersebut; pergantian model pun hanya berarti mengubah Model ID, tanpa perlu mendaftarkan akun dan memelihara kunci secara terpisah untuk tiap vendor.

2 Konfigurasi dari Nol Penyedia Model Kustom di DeepSeek Harness
2.1 Membuka Antarmuka Konfigurasi Model DeepSeek Harness
Cara tercepat untuk menjalankan Harness secara lokal adalah dengan perintah npm resmi, dan Node.js harus sudah terpasang terlebih dahulu:
npx @deepseek-ai/dsh web
# Secara default membuka Web UI lokal: http://127.0.0.1:3080
Setelah masuk ke antarmuka, klik berurutan Pengaturan → Model → Tambahkan Penyedia Model → API Model Kustom, lalu formulir konfigurasi penyedia akan muncul. Versi desktop resmi menyediakan paket instalasi untuk macOS Apple Silicon dan Windows 64-bit, dengan jalur konfigurasi yang sama.
2.2 Mengisi Informasi Penyedia DeepSeek Harness
| Item pengaturan | Fungsi | Poin pengisian |
|---|---|---|
| Provider ID | Identitas unik penyedia | Harus huruf kecil, tidak dapat diganti namanya setelah dibuat, misalnya apiyi |
| Nama tampilan | Nama yang muncul di menu model | Bisa ditulis “APIYI Kompatibel OpenAI” |
| Protokol API | Format permintaan dan respons | Sesuai dengan Base URL, lihat 2.3 |
| Base URL | Alamat layanan API | Perhatikan prefiks versi, lihat 2.4 |
| Kunci API | Kredensial autentikasi identitas | Disimpan di file kredensial, antarmuka hanya menampilkan pratinjau tersamarkan |
| Model ID | Nama model yang sebenarnya dipanggil | Harus sama persis dengan daftar model gateway |
| Context Window / Max Output Tokens | Panjang konteks dan output maksimum | Isi sesuai spesifikasi aktual model |
| Input Type | Input teks atau gambar | Centang gambar hanya untuk model visual |
| Reasoning Effort | Tingkat penalaran dan pemetaan parameter | Hanya tambahkan level yang benar-benar didukung model |
Provider ID tidak dapat diganti namanya karena konfigurasi model, riwayat sesi, dan referensi kredensial semuanya mengarah ke ID ini. Jika perlu menggantinya, buat penyedia baru terlebih dahulu, lalu hapus yang lama.
Tombol “Dapatkan model yang tersedia” pada formulir akan mencoba membaca daftar model dari gateway. Jika gateway tidak menyediakan daftar model standar, atau format responsnya di luar cakupan yang dikenali Harness, cukup tambahkan Model ID secara manual—hasilnya sama.
2.3 Memilih protokol API DeepSeek Harness
API model kustom Harness mendukung empat protokol: OpenAI Chat Completions, OpenAI Responses, Anthropic Messages, dan Gemini API. Satu penyedia hanya bisa diikat ke satu protokol, jadi kalau gateway yang sama membuka tiga pintu masuk protokol, Anda perlu membuat tiga penyedia.
Pilihan protokol mengikuti keluarga model. GPT, DeepSeek, dan sebagian besar model dalam negeri paling aman lewat OpenAI Chat Completions; seri Claude bisa memakai Anthropic Messages agar fitur aslinya tetap terjaga; seri Gemini memakai Gemini API. Protokol Responses cocok untuk skenario yang butuh respons terstruktur dan pemanggilan tool, dengan syarat gateway dan model target sama-sama mendukung antarmuka tersebut.
2.4 Mengonfigurasi instans DeepSeek Harness dengan APIYI
APIYI secara resmi memberikan pemetaan protokol dan Base URL sebagai berikut:
| Protokol | Base URL APIYI | Model yang cocok | Platform yang tersedia |
|---|---|---|---|
| Kompatibel OpenAI (Chat Completions) | https://api.apiyi.com/v1 |
GPT, DeepSeek, dll. | APIYI apiyi.com, API resmi tiap vendor |
| Anthropic native | https://api.apiyi.com |
Seri Claude | APIYI, Anthropic resmi |
| Gemini | https://api.apiyi.com/v1beta |
Seri Gemini | APIYI, Google resmi |
Protokol Anthropic memakai domain root, adapter akan menyusun sendiri jalur setelahnya. Kalau setelah domain root Anda menambahkan /v1 lagi, jalurnya bisa dobel dan hasilnya 404. Untuk cara integrasi protokol Responses, cek dulu dokumentasi APIYI Responses API sebelum mengisi.
Selain konfigurasi lewat antarmuka, Harness juga mendukung pengeditan file konfigurasi secara manual, lokasinya di $DSH_HOME/profiles/web/cordis.patch.yml. Berikut templat penyedia kompatibel OpenAI APIYI yang disusun mengikuti struktur konfigurasi resmi:
- id: llm-pi-ai
config:
providers:
apiyi:
apiKeyEnv: APIYI_API_KEY # membaca kunci dari variabel lingkungan
api: openai-completions # protokol OpenAI Chat Completions
baseURL: https://api.apiyi.com/v1 # endpoint kompatibel OpenAI APIYI
models:
- id: MODEL_ID_FROM_APIYI # ganti dengan ID model yang benar-benar tersedia di akun
Langkah penggunaannya:
- Setel variabel lingkungan
APIYI_API_KEY; - Ganti
MODEL_ID_FROM_APIYIdengan nama model yang benar-benar tersedia di konsol APIYI; - Simpan konfigurasi, lalu pilih penyedia
apiyidan model yang sesuai di pemilih model Harness; - Lakukan satu percakapan sederhana untuk memastikan antarmuka berjalan normal.
Templat ini menunjukkan struktur konfigurasi resmi; untuk nama model, ikuti daftar yang bisa dipanggil di akun Anda sendiri. Perubahan konfigurasi model biasanya berlaku pada permintaan berikutnya, tanpa perlu me-restart Web UI. Konfigurasi lewat antarmuka cocok untuk menambah model dan mengubah kunci sehari-hari, sedangkan file konfigurasi cocok untuk mengatur parameter kompatibilitas, mode inferensi, timeout, dan retry serta pengaturan lanjutan lainnya.
Sebelum menyambungkan ke Harness, sebaiknya validasi Key dan Model ID secara terpisah lewat skrip, sehingga masalah “gateway bisa dipakai” dan “konfigurasi Harness sudah benar” bisa ditelusuri secara terpisah:
import os
from openai import OpenAI
client = OpenAI(
api_key=os.environ["APIYI_API_KEY"],
base_url="https://api.apiyi.com/v1" # endpoint kompatibel OpenAI APIYI apiyi.com
)
resp = client.chat.completions.create(
model="MODEL_ID_FROM_APIYI", # samakan dengan Model ID yang diisi di Harness
messages=[{"role": "user", "content": "用一句话介绍你自己"}],
max_tokens=100
)
print(resp.choices[0].message.content)
🚀 Saran agar cepat lancar: pengguna baru bisa mendaftar di APIYI apiyi.com lalu mengambil kuota uji gratis, gunakan dulu skrip di atas untuk memastikan Model ID bisa dipakai, baru kemudian menuliskannya ke konfigurasi Harness. Waktu troubleshooting keseluruhan akan jauh lebih singkat.
3 Antarmuka DeepSeek Harness Bisa Terhubung, tetapi Mengapa Model Tetap Gagal Dipanggil
Dokumentasi resmi Harness secara jelas menyebutkan: meskipun alamat API dan kunci sudah benar, gateway tetap bisa menolak permintaan. Penyebabnya adalah perbedaan persyaratan antar antarmuka kompatibel terkait peran pesan, panjang output, dan parameter thinking. Tiga parameter compat berikut digunakan untuk mengatasi masalah tersebut, dan sebaiknya diaktifkan sesuai kebutuhan berdasarkan error yang benar-benar dikembalikan oleh antarmuka.
3.1 Kompatibilitas Peran Developer
Spesifikasi OpenAI versi baru memperkenalkan role: developer, sementara sebagian gateway kompatibel hanya mengenali system. Jika muncul situasi “semua permintaan gagal” atau “hanya model reasoning yang gagal”, Anda dapat menonaktifkan peran developer:
compat:
supportsDeveloperRole: false
Setelah opsi ini diaktifkan, adaptor akan menyesuaikan cara penanganan peran dalam permintaan agar sesuai dengan format yang diterima gateway.
3.2 Kompatibilitas Parameter Output Maksimum
Antarmuka OpenAI yang baru menggunakan max_completion_tokens untuk menyatakan output maksimum, sedangkan sebagian gateway hanya menerima max_tokens tradisional. Keduanya memiliki makna yang sama; jika nama field tidak konsisten, validasi parameter akan gagal. Pengaturannya adalah:
compat:
maxTokensField: max_tokens
3.3 Kompatibilitas Mode Thinking DeepSeek
Sebagian model DeepSeek mengaktifkan mode thinking secara default. Saat tingkat reasoning diatur ke off di Harness, sebagian protokol kompatibel hanya akan menghilangkan parameter reasoning, sehingga model tetap berpikir sesuai perilaku default—inilah yang menyebabkan “off tidak bisa mematikan thinking”. Untuk itu, pihak resmi menyediakan format thinking khusus DeepSeek:
compat:
thinkingFormat: deepseek
Setelah diaktifkan, saat thinking dimatikan adaptor akan secara eksplisit mengirim {"thinking": {"type": "disabled"}}, dan saat diaktifkan mengirim {"thinking": {"type": "enabled"}}. Contoh resmi ditujukan untuk model DeepSeek V4 di balik gateway kompatibel OpenAI. Pada gateway multi-model, parameter ini dapat diatur khusus hanya untuk model DeepSeek, sementara model seperti GPT dan Claude tetap menggunakan default.
Terkait tingkat reasoning, Harness memungkinkan pemetaan off, low, medium, high, max pada antarmuka ke nilai parameter yang benar-benar diterima API. Hanya masukkan level yang benar-benar didukung model ke dalam konfigurasi, agar pengguna tidak memilih level tidak valid yang menyebabkan error pada permintaan. Contoh lengkap setelah menggabungkan ketiga parameter kompatibilitas adalah sebagai berikut:
- id: llm-pi-ai
config:
providers:
apiyi:
apiKeyEnv: APIYI_API_KEY
api: openai-completions
baseURL: https://api.apiyi.com/v1
compat:
supportsDeveloperRole: false
maxTokensField: max_tokens
models:
- id: MODEL_ID_FROM_APIYI
3.4 Penanganan Cepat Error Umum DeepSeek Harness
| Error atau Gejala | Kemungkinan Penyebab | Cara Menangani |
|---|---|---|
| MISSING_CREDENTIAL | Kunci belum dikonfigurasi | Periksa kunci API dan nama variabel lingkungan |
| UNKNOWN_MODEL | ID model belum terdaftar | Tambahkan ID model yang benar di bawah provider |
| HTTP 401 | Kunci tidak valid atau izin kurang | Periksa isi kunci dan grup tempatnya |
| HTTP 404 | Jalur Base URL salah | Periksa protokol dan prefiks versi (/v1, domain root, /v1beta) |
| Daftar model kosong | Gateway tidak mendukung antarmuka daftar model standar | Tambahkan ID model secara manual |
| Semua permintaan gagal | Konflik format peran atau parameter | Periksa parameter kompatibilitas compat |
| Hanya model reasoning yang gagal | Peran Developer tidak kompatibel | Atur supportsDeveloperRole: false |
| off tidak bisa mematikan thinking | Model mengaktifkan thinking secara default | Atur thinkingFormat: deepseek |
| Antarmuka pencarian mengembalikan 503 | Token grup tidak memiliki izin tool | Ganti token grup default atau svip |
| Percakapan normal, akses internet tidak tersedia | Tool pencarian belum terintegrasi atau protokol tidak didukung | Periksa kemampuan tool dan konfigurasi klien |
Delapan item pertama mengacu pada dokumentasi konfigurasi resmi Harness, sedangkan masalah terkait grup berasal dari dokumentasi resmi APIYI. Urutan penanganan disarankan dari atas ke bawah: pertama pastikan kredensial, lalu ID model, kemudian jalur, dan terakhir kompatibilitas parameter.
4 Menambahkan Kemampuan Pencarian Web ke DeepSeek Harness
4.1 Membedakan Pencarian Bawaan Model dan API Pencarian Independen
Pemanggilan percakapan biasa yang berhasil hanya membuktikan bahwa kunci API dapat digunakan, ID model sudah benar, dan protokol percakapan pada dasarnya kompatibel. Kemampuan pencarian web juga menuntut model mendukung alat terkait, permintaan mendeklarasikan alat dengan benar, layanan API mendukung protokol alat tersebut, Harness dapat menangani respons alat, atau pengembang mengintegrasikan pencarian secara terpisah di sisi aplikasi. Jadi, percakapan yang berhasil dan pencarian web yang berhasil adalah dua langkah verifikasi yang terpisah.
Dalam ekosistem DeepSeek, kemampuan pencarian web memiliki dua jalur teknis:

| Dimensi | Jalur A: Alat Sisi Server Bawaan Model | Jalur B: API Search / Fetch Independen |
|---|---|---|
| Cara pemanggilan | Mendeklarasikan deepseek_web_search dan deepseek_read_url dalam permintaan percakapan |
Program secara aktif meminta /v1/tools/search dan /v1/tools/fetch |
| Siapa yang menentukan pencarian | Model memutuskan sendiri | Pengembang atau logika alat Agent |
| Eksekusi alat | Server DeepSeek melakukan pencarian dan penggabungan konteks | Klien memproses sendiri setelah menerima hasil |
| Cakupan model | Pengumuman resmi secara eksplisit menyebut deepseek-flash |
Tidak bergantung pada model; hasil dapat digunakan ulang oleh model apa pun |
| Dasar penagihan | Ditagih berdasarkan jumlah istilah pencarian aktual, jumlah halaman web yang diambil, dan sebagainya | Ditagih berdasarkan jumlah permintaan yang berhasil, tanpa menghabiskan Token model |
| Saluran yang tersedia saat ini | API resmi DeepSeek | API resmi DeepSeek, APIYI |
4.2 Cara kerja pencarian bawaan model
Pada 13 November 2026, DeepSeek membuka sejumlah kemampuan aplikasi di balik App, di mana pencarian internet dan pembacaan tautan disediakan dalam bentuk alat sisi server. Cukup deklarasikan dalam daftar alat permintaan:
[
{"type": "deepseek_web_search", "name": "deepseek_web_search"},
{"type": "deepseek_read_url", "name": "deepseek_read_url"}
]
Setelah dideklarasikan, model akan menentukan sendiri apakah perlu terhubung ke internet dan menghasilkan kata kunci pencarian; server DeepSeek yang mengeksekusi pencarian dan mengembalikan jawaban dengan kutipan sumber. Setelah mode berpikir diaktifkan, pencarian ditingkatkan menjadi proses multi-langkah; model dapat mencari beberapa kata kunci, membuka halaman web, mencari dalam halaman, dan melakukan verifikasi silang. Dokumentasi resmi menunjukkan maksimal sekitar 20 pemanggilan alat sebelum menjawab. deepseek_read_url hanya mengenali URL dalam pesan pengguna terakhir, dengan maksimal 10 tautan berbeda yang dipertimbangkan.
Pengembang tetap perlu menangani blok konten yang dikembalikan, informasi kutipan, peristiwa streaming, dan riwayat multi-turn. Menurut pengumuman resmi, integrasi alat lengkap tingkat percakapan ini dijalankan oleh deepseek-flash (DeepSeek-V4.1-Flash). Menurut dokumentasi APIYI, pekerjaan kompatibilitas untuk memanggil pencarian bawaan semacam ini melalui gateway dengan klien seperti Harness, Claude Code masih dalam perencanaan lanjutan; untuk menggunakan jalur A saat ini, sebaiknya hubungkan langsung ke API resmi DeepSeek.
4.3 Integrasi Search / Fetch Mandiri APIYI
APIYI meluncurkan antarmuka alat mandiri DeepSeek Search & Fetch pada 21 Oktober 2026, yang bersesuaian dengan deepseek-search dan deepseek-fetch. Search mengembalikan hasil pencarian terstruktur, sedangkan Fetch mengambil halaman web tertentu dan mengembalikan isi Markdown. Permintaan tidak perlu menyertakan ID model dan tidak menghabiskan Token model; penagihan dilakukan berdasarkan jumlah panggilan yang berhasil.
Contoh berikut melakukan pencarian terlebih dahulu, lalu mengambil halaman web yang berada di peringkat pertama:
import os
import requests
BASE = "https://api.apiyi.com/v1/tools" # Antarmuka alat mandiri APIYI
headers = {"Authorization": f"Bearer {os.environ['APIYI_API_KEY']}"}
search = requests.post(
f"{BASE}/search",
headers=headers,
json={"query": "DeepSeek Harness 插件", "count": 5},
timeout=60,
)
search.raise_for_status()
results = search.json()["results"]
if results:
url = results[0]["url"]
fetch = requests.post(
f"{BASE}/fetch",
headers=headers,
json={"url": url},
timeout=60,
)
if fetch.ok:
print(fetch.json()["content"])
Pengelompokan token perlu diperhatikan secara khusus: grup default dan svip dapat memanggil kedua antarmuka ini, sedangkan token grup ClaudeCode tidak dapat memanggilnya secara langsung; dokumentasi mencatat kasus pengembalian 503. Pengujian mandiri dalam dokumentasi APIYI menunjukkan bahwa Search mengembalikan 5 hasil dalam sekitar 1,8 detik, dan 20 permintaan bersamaan semuanya mengembalikan 200; Fetch yang mengakses halaman tidak terjangkau mengembalikan kegagalan tanpa penagihan. Data ini berasal dari pengujian platform itu sendiri, sedangkan kinerja aktual dipengaruhi oleh jaringan dan situs target. Dari sisi harga, dokumentasi mencantumkan harga internal sebesar $0,90 per 1000 panggilan, dan setelah ditambah bonus pengisian ulang, jumlah yang dibayarkan menjadi lebih rendah; angka pastinya mengacu pada konsol.
Agar Agent di Harness dapat menggunakan logika ini secara mandiri, logika tersebut perlu dikemas menjadi plugin alat. Plugin Harness ditulis dalam TypeScript, mendaftarkan alat melalui objek konteks ctx, dan saat plugin dilepas, framework akan otomatis membersihkan alat serta event yang terdaftar. Saat mengemasnya, disarankan mendaftarkan search dan fetch sebagai dua alat terpisah, sehingga model menerima daftar hasil lebih dahulu, lalu memutuskan halaman mana yang akan diambil.
💡 Saran teknis: Search / Fetch mandiri terpisah dari model, sehingga hasil pencarian yang sama dapat diserahkan ke berbagai model seperti GPT, Claude, dan DeepSeek untuk diproses. Dengan APIYI apiyi.com, satu Key dapat sekaligus mengelola pemanggilan model dan alat pencarian, sehingga memudahkan perbandingan kualitas jawaban berbagai model berdasarkan bahan yang sama di Harness.
5 Cara Merancang Agent Multi-Model DeepSeek Harness
5.1 Pilih model yang berbeda sesuai tugas
Nilai integrasi multi-model terletak pada alokasi model berdasarkan tugas. Agent coding dapat memakai model yang unggul dalam pemrograman; tugas berfrekuensi tinggi seperti perapian dokumen dan penulisan ulang ringkasan cocok memakai model berbiaya rendah; sedangkan analisis tangkapan layar dan pemahaman grafik wajib memakai model visual yang mendukung input gambar, dengan mencentang opsi gambar di Input Type.
Sebagai contoh model resmi DeepSeek, DeepSeek-V4.1-Flash mendukung pemahaman gambar, sedangkan DeepSeek-V4-Pro tidak, dan harga keduanya juga berbeda beberapa kali lipat. Di Harness, konfigurasikan keduanya sebagai dua Model ID di bawah provider yang sama, lalu ganti sesuai tugas di dalam sesi. Dengan begitu, hasil dan biaya bisa sama-sama terjaga.
5.2 Kelola pemanggilan model DeepSeek Harness dan kemampuan pencarian secara berlapis

Struktur yang direkomendasikan terbagi menjadi tiga lapis. Lapisan eksekusi ditangani Harness untuk loop tugas, kompresi konteks, pemuatan plugin, dan kontrol izin; lapisan model ditangani gateway API untuk konversi protokol, routing model, dan penagihan; lapisan alat menyediakan informasi eksternal melalui antarmuka independen seperti Search / Fetch. Ketiga lapisan dapat diganti secara terpisah: mengganti model cukup mengubah Model ID, mengganti layanan pencarian cukup mengubah plugin alat, dan logika eksekusi tetap sama.
Pemisahan berlapis juga memberi manfaat keamanan. Evaluasi terkontrol Laboratorium Zhuque Tencent terhadap Harness menunjukkan bahwa konten tidak tepercaya seperti halaman web, file, dan Skills dapat memengaruhi perilaku Agent melalui injeksi petunjuk tidak langsung. Setelah lapisan alat dipisahkan dari lapisan eksekusi, kita dapat menambahkan tahap penyaringan dan konfirmasi terpadu sebelum hasil pencarian masuk ke konteks dan sebelum alat sensitif dijalankan.
5.3 Saran deployment DeepSeek Harness di lapangan
- Konfigurasi model: Satu protokol untuk satu provider, Provider ID memakai huruf kecil dan ditetapkan sekali saja; Model ID selalu disalin dari konsol gateway.
- Manajemen kunci: Harness menyimpan kunci di
$DSH_HOME/.credentials.yaml; file konfigurasi hanya mereferensikan variabel lingkungan, agar Key plaintext tidak masuk ke konfigurasi bersama atau repositori kode. - Uji kompatibilitas: Setiap kali mengintegrasikan model baru, verifikasi percakapan biasa, menonaktifkan thinking, output panjang, dan input gambar secara berurutan, lalu aktifkan parameter
compatsesuai pesan error. - Pemanggilan alat: Kendalikan jumlah plugin. Umpan balik komunitas menunjukkan bahwa setelah memasang lebih dari belasan plugin, dapat muncul luapan konteks dan kenaikan konsumsi Token; deskripsi alat pencarian yang tetap ringkas lebih stabil.
- Pencatatan biaya: Token model dan pemanggilan alat ditagih secara terpisah; sebaiknya hitung keduanya secara terpisah di backend gateway. Konsol APIYI apiyi.com dapat menampilkan penggunaan berdasarkan Key, cocok untuk memberikan Key terpisah bagi tiap Agent guna atribusi biaya.
Selain itu, sebelum meningkatkan versi Harness, cadangkan konfigurasi di bawah $DSH_HOME. Komunitas pernah mencatat kasus konfigurasi plugin pihak ketiga hilang setelah peningkatan versi dan butuh beberapa jam untuk memulihkannya.
FAQ Umum
Q1: Apakah DeepSeek Harness hanya bisa menggunakan model DeepSeek?
Harness mendukung integrasi layanan apa pun yang kompatibel dengan salah satu dari empat protokol melalui API model kustom, termasuk seri OpenAI, Claude, Gemini, serta berbagai gateway API dan layanan model yang dibangun sendiri. Model resmi DeepSeek hanyalah salah satu opsi.
Q2: Mengapa perlu membuat beberapa penyedia untuk gateway yang sama?
Harness menetapkan bahwa satu penyedia hanya terikat pada satu protokol. APIYI membuka tiga pintu masuk sekaligus: kompatibel OpenAI, Anthropic, dan Gemini. Jika ingin memanggil GPT, Claude, dan Gemini masing-masing dengan protokol aslinya, maka perlu membuat tiga penyedia, dengan Base URL masing-masing `/v1`, domain root, dan `/v1beta`.
Q3: Bagaimana cara memastikan ID model mana yang harus diisi?
Coba dulu fitur “Dapatkan model yang tersedia”; jika tidak terbaca, salin nama yang tepat dari daftar model di konsol APIYI apiyi.com lalu tambahkan secara manual. ID model membedakan huruf besar-kecil dan sufiks versi; perbedaan apa pun akan memicu UNKNOWN_MODEL atau error gateway.
Q4: Setelah terhubung melalui APIYI, apakah bisa langsung menggunakan deepseek_web_search?
Saat ini APIYI sudah mendukung antarmuka Search / Fetch mandiri DeepSeek, sedangkan pekerjaan kompatibilitas untuk memanggil pencarian bawaan model melalui klien seperti Harness masih dalam perencanaan. Pada tahap ini disarankan menggunakan `/v1/tools/search` dan `/v1/tools/fetch` dari APIYI yang dibungkus sebagai alat Agent; jika membutuhkan pencarian bawaan, hubungkan langsung ke API resmi DeepSeek.
Q5: Antarmuka pencarian mengembalikan 503, tetapi percakapan berjalan normal. Apa penyebabnya?
Penyebab paling umum adalah pengelompokan token. Token dari grup ClaudeCode tidak dapat memanggil antarmuka alat mandiri secara langsung; ganti dengan Key dari grup default atau svip. Anda dapat membuat token khusus untuk alat pencarian dengan grup yang sesuai di backend APIYI apiyi.com, dan mengelolanya terpisah dari Key untuk pemanggilan model.
Q6: Apa saja batasan dalam integrasi banyak model di DeepSeek Harness?
Harness masih dalam versi pratinjau pengembang, sehingga struktur konfigurasi dapat berubah seiring versi; tingkat penerusan gateway masing-masing terhadap Responses, parameter inferensi, dan protokol alat berbeda-beda, sehingga perlu diverifikasi model per model. Terlalu banyak plugin akan meningkatkan biaya konteks dan Token, dan kualitas hasil tugas kompleks juga bergantung pada konfigurasi plugin serta manajemen proses eksekusi.
Ringkasan
Mekanisme adaptasi model terbuka DeepSeek Harness memungkinkan satu framework Agent memanggil model dari berbagai vendor melalui gateway terpadu. Saat menerapkannya, perhatikan beberapa poin berikut:
- Protokol menentukan Provider: satu protokol dibuatkan satu Provider; prefiks versi Base URL harus benar-benar sesuai dengan protokolnya.
- ID model disalin persis dari gateway: salin dari konsol; jika daftar tidak dapat dibaca, tambahkan secara manual.
- Parameter kompatibilitas diaktifkan berdasarkan error: tiga hal—role developer, field
max_tokens, dan format thinking DeepSeek—mencakup sebagian besar masalah “bisa terhubung tetapi tidak bisa dipakai”. - Kemampuan koneksi internet direncanakan terpisah: pencarian bawaan menggunakan API resmi DeepSeek, sedangkan Search / Fetch independen dapat dipanggil melalui gateway dan dibungkus menjadi tool.
- Pemisahan lapisan dan tata kelola: lapisan eksekusi, lapisan model, dan lapisan tool dipisahkan; kunci, versi, dan biaya dikelola secara terpisah.
Sebaiknya mulai dengan satu model untuk memvalidasi alur “verifikasi skrip → konfigurasi Harness → percakapan sederhana”, lalu tambahkan lebih banyak model dan alat pencarian secara bertahap. Kami merekomendasikan mengambil kuota uji coba gratis melalui APIYI apiyi.com, lalu menggunakan satu Key untuk memvalidasi seluruh alur multi-model serta Search / Fetch.
📚 Referensi
- Dokumentasi konfigurasi model DeepSeek Harness: field provider kustom dan parameter kompatibilitas compat
- Tautan:
deepseek-harness.github.io/deepseek-harness/guide/providers -
Keterangan: penjelasan resmi untuk supportsDeveloperRole, maxTokensField, dan thinkingFormat
-
Repositori GitHub DeepSeek Harness: kode sumber, Releases, dan cara memulai
- Tautan:
github.com/deepseek-ai/deepseek-harness -
Keterangan: penjelasan pembaruan versi dan tahap pratinjau pengembang
-
Dokumentasi alat koneksi internet DeepSeek: deepseek_web_search dan deepseek_read_url
- Tautan:
api-docs.deepseek.com/zh-cn/guides/web_tools/ -
Keterangan: cara mendeklarasikan pencarian bawaan, batasan, dan dasar penagihan
-
Panduan konfigurasi Base URL APIYI: penjelasan tiga jalur protokol
- Tautan:
help.apiyi.com/apiyi-base-url-v1-claude-gemini-endpoint-config-guide.html -
Keterangan: skenario penggunaan
/v1, domain root, dan/v1beta -
Dokumentasi DeepSeek Search & Fetch APIYI: antarmuka tool independen dan persyaratan grup
- Tautan:
docs.apiyi.com/api-capabilities/deepseek-search-fetch/overview - Keterangan: parameter permintaan, grup token, dan penjelasan penagihan
Penulis: Tim Teknis APIYI
Diskusi teknis: Jika Anda mengalami masalah selama proses konfigurasi, silakan hubungi kami melalui halaman utama APIYI apiyi.com. Untuk penjelasan antarmuka lainnya, lihat pusat dokumentasi docs.apiyi.com.
