DeepSeek Harness'ta Herhangi Bir Model Nasıl Çalıştırılır?

DeepSeek Harness (dsh) DeepSeek'in kendi modelleriyle birlikte gelir, ancak onlara bağlı değilsiniz. Harness, model sağlayıcılarını bir yapılandırma olarak ele alır: bir sağlayıcı bloğunu herhangi bir OpenAI uyumlu uç noktaya yönlendirin, ona bir kimlik bilgisi referansı verin ve aracı oturumlarınız o URL'nin arkasındaki modelde çalışsın. Yerel bir Ollama örneği, bir şirket ağ geçidi, DashScope'un uyumlu modu aracılığıyla Qwen veya Anthropic ve OpenAI gibi büyük katalog sağlayıcıları hepsi aynı bloğa bağlanır.

Bu kılavuz, o bloğu anahtar anahtar gezdirir, ardından üç çalışan tarif oluşturur: yerel bir model, barındırılan bir OpenAI uyumlu uç nokta ve yerleşik katalog sağlayıcıları. Burada alıntılanan her şey, master dalındaki resmi sağlayıcılar kılavuzundan alınmıştır, 20 Ağustos 2026'da çekilmiştir. Başlangıçta bir uyarı: dsh bir geliştirici önizlemesidir ve README, uyumluluğu bozan değişiklikler olacağı konusunda büyük harflerle uyarır. Üretime herhangi bir şey kopyalamadan önce belgeleri yüklü sürümünüzle karşılaştırın.

Harness'ın kendisine yeniyseniz, DeepSeek Harness'ın ne olduğu ve nasıl çalıştığı ile başlayın, ardından sağlayıcı entegrasyonu için buraya geri dönün.

Bir aracı harness'ında modelleri neden değiştirmeliyiz?

Bir aracı harness'ı bir döngüdür: model planlar, araçları çağırır, sonuçları okur ve tekrarlar. Harness döngüye sahiptir; model bir bileşendir. Bileşeni değiştirmenizin üç nedeni:

Maliyet. Aracı oturumları jetonları hızla tüketir çünkü her araç sonucu bağlama geri beslenir. Rutin oturumları daha ucuz bir modele veya DeepSeek V4-Pro yerine V4-Flash'a yönlendirmek, iş akışınızı değiştirmeden faturanızı değiştirir. İhtiyaç duyan oturumlar için pahalı bir öncü modeli yapılandırılmış olarak tutabilirsiniz.

Veri yerelliği. Bazı kod tabanları binayı terk edemez. Kendi donanımınızda çalışan bir modele işaret eden bir sağlayıcı bloğu, istemlerin, dosya içeriklerinin ve araç çıktılarının ağı asla geçmemesi anlamına gelir. Aynı harness, aynı kullanıcı arayüzü, sıfır çıkış.

Yerel geliştirme. Eklentiler oluştururken veya aracı davranışını test ederken, her iterasyonun API kredilerine mal olmasını veya ağınıza bağlı olmasını istemezsiniz. Küçük bir yerel model, döngüyü test etmek için yeterince hızlı yanıt verir ve davranış önemli olduğunda gerçek modeli geri yüklersiniz.

Tasarım, dsh'nin mimarisinden kaynaklanır: harness'taki her şey bir eklentidir ve model adaptörü değiştirilebilir parçalardan biridir. Sağlayıcı rotaları, depo'nun eklenti yapılandırma kataloğunda “bu örneğin sahip olduğu sağlayıcı rotalarını” tutan dsh-llm-pi-ai eklentisine aittir. Mekanizma budur. Kullanıcıya dönük yüzey bir YAML bloğudur.

Sağlayıcı bloğu, anahtar anahtar

Özel sağlayıcılar $DSH_HOME/settings.yaml içinde bulunur ve bunları web arayüzünden Ayarlar → Modeller altında da oluşturabilirsiniz. İşte resmi belgelerden doğrudan örnek:

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]

Her anahtar ne işe yarar:

• my-gateway sağlayıcı kimliğidir. Kalıcı bir tanımlayıcı olduğundan, kullanabileceğiniz bir isim seçin; UI'da gösterilen görünen ad ayrı olarak ayarlanır.
• apiKeyEnv, API anahtarınızı tutan ortam değişkeninin adıdır. Ayarlar dosyası asla sırrın kendisini içermez, yalnızca bu referansı içerir. Gerçek anahtarın nerede yaşadığına dair daha fazla bilgi aşağıdadır.
• api iletişim protokolünü bildirir. openai-completions, OpenAI uyumlu uç noktalar için belgelenmiş değerdir ve "herhangi bir model" vaadinin çalışmasını sağlayan şey budur: çoğu ağ geçidi, yerel çalışma zamanı ve barındırılan sağlayıcı bu protokolü konuşur.
• baseURL, harness'ın istek gönderdiği uç nokta köküdür.
• models, bu sağlayıcı aracılığıyla kullanılabilen model kimliklerini listeler. Her girişin en az bir id'ye ihtiyacı vardır ve bu, uç noktanın istek gövdesinde beklediğiyle eşleşmelidir.
• input, modele göre modaliteleri bildirir. Özel modeller varsayılan olarak yalnızca metinlidir, bu nedenle bir görme modeli açıkça input: [text, image] bildirmelidir, aksi takdirde görüntü ekleri ona ulaşmaz. Ayrıca sağlayıcıdaki her model için bir yedek ayarı yapan bir rota düzeyinde defaultInput vardır; model düzeyinde bir input bunu geçersiz kılar.
• compat, varsayılan OpenAI davranışından sapan uç noktalar için uyumluluk anahtarlarını tutar. Belgeler iki tanesini belirtir: developer rolünü reddeden arka uçlar için supportsDeveloperRole: false ve eski çıktı sınırı alan adını isteyen arka uçlar için maxTokensField: max_tokens. Uyumluluk, rota düzeyinde veya modele göre ayarlanabilir.

Bilmeye değer bir kolaylık: web arayüzü aracılığıyla özel bir sağlayıcı eklediğinizde, "Kullanılabilir modelleri getir" seçeneği uç noktanın OpenAI uyumlu GET /models rotasını sorgular ve model listesini sizin için doldurur. Uç noktanız bu rotayı uyguluyorsa, manuel yazmayı atlarsınız.

Gerçek API anahtarının bulunduğu yer

Sırlar, yalnızca yazılabilir olarak $DSH_HOME/.credentials.yaml içinde saklanır. Bir anahtarı UI aracılığıyla kaydettikten sonra, dsh yalnızca sansürlenmiş bir tanımlayıcı döndürür; gerçek değer bir daha asla gösterilmez. settings.yaml referansları (apiKeyEnv adları, kimlik bilgisi tanımlayıcıları) tutar, asla anahtarların kendisini tutmaz. Bu ayrım, bir ayar dosyasını herhangi bir sızıntı olmadan taahhüt edebileceğiniz veya paylaşabileceğiniz ve sağlayıcı yapılandırmasına dokunmadan bir anahtarı değiştirebileceğiniz anlamına gelir.

Tarif 1: Ollama aracılığıyla yerel bir model çalıştırma

Ollama, http://localhost:11434/v1 adresinde bir OpenAI uyumlu API sunar ve Ollama bunu kendi OpenAI uyumluluk kılavuzunda belgeler. dsh herhangi bir temel URL'ye openai-completions konuştuğu için eşleştirme basittir.

[DOĞRULA: dsh belgeleri Ollama'ya özel bir örnek göstermez; bu tarif, belgelenmiş özel sağlayıcı şemasını Ollama'nın belgelenmiş OpenAI uyumlu uç noktasına uygular. Dahili olarak yayınlamadan önce kurulumunuzda test edin.]

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

Buna dair notlar:

• Ollama yerel olarak bir API anahtarı gerektirmez, ancak şema bir kimlik bilgisi referansı bekler, bu yüzden sahte bir değer ayarlayın: export OLLAMA_API_KEY=ollama. Ollama gönderdiğiniz her şeyi yok sayar.
• Model id, Ollama'nın sunduğu etiketle eşleşmelidir. ollama list komutunu çalıştırın ve adları, etiket dahil olmak üzere tam olarak kopyalayın.
• Modeli önce çekin (ollama pull gpt-oss:20b) ve dsh'ye bağlamadan önce sunucunun yanıt verdiğini doğrulayın. Tam yerel kurulumu Ollama kullanarak GPT-OSS nasıl çalıştırılır makalemizde ele aldık ve aynı desen, donanımınız yeterliyse Kimi K3 gibi diğer açık ağırlıklı modeller için de geçerlidir.

Hızlı bir sağlama kontrolü sizi kafa karıştırıcı bir aracı oturumundan kurtarır: dsh yapılandırmasına dokunmadan önce Apidog'da http://localhost:11434/v1/models adresine istek gönderin. Eğer bu istek model listenizi döndürürse, temel URL doğrudur, sunucu çalışıyordur ve dsh UI'ındaki "Kullanılabilir modelleri getir" de çalışacaktır. Çalışmazsa, hiçbir harness yapılandırması bunu düzeltemez.

Beklenti yönetimi: aracı harness'ları araç çağırmaya ve uzun bağlama yoğun olarak dayanır. Küçük yerel modeller test için döngüyü yönetir, ancak planlama konusunda daha kötü performans gösterir ve harness'ın etrafında inşa edildiği öncü modellere göre araç çağrılarını daha sık düşürürler. Bu, eklenti geliştirme için sorun değil; ancak gerçek iş için sinir bozucu olabilir.

Tarif 2: Barındırılan bir OpenAI uyumlu uç nokta (DashScope aracılığıyla Qwen)

Barındırılan bir örnek için, OpenAI uyumluluğunu belgeleyen bir satıcı seçin, varsaydığınız birini değil. Alibaba Cloud Model Studio (DashScope) bunu yapar: OpenAI uyumluluk sayfası, Qwen modelleri için bölgesel, çalışma alanına özel alan adları (Singapur için: https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/compatible-mode/v1) ve DASHSCOPE_API_KEY ortam değişkeni aracılığıyla kimlik doğrulama ile bir /compatible-mode/v1 uç noktasını belgeler.

dsh şemasına eşleştirildiğinde:

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

{WorkspaceId} yerine Model Studio konsolunuzdaki gerçek çalışma alanı alan adınızı yazın ve mevcut kimlikler için satıcının model listesini kontrol edin; amiral gemisi katmanının bir özetini Qwen 3.8 API kılavuzumuzda tutuyoruz. Aynı desen, belgelenmiş OpenAI uyumluluğuna sahip herhangi bir satıcıya kadar uzanır: Moonshot'ın Kimi API'si, OpenRouter, bir vLLM dağıtımı veya şirketinizin dahili ağ geçidi. Değişen tek kısımlar baseURL, ortam değişkeni adı ve model kimlikleridir. Eğer Codex'te açık kaynak modelleri yapılandırdıysanız, bu size tanıdık gelecektir; dsh'nin YAML bloğu, Codex'in model_providers yapılandırmasıyla aynı rolü oynar.

İki barındırılan uç nokta özelliği:

• Satıcının uç noktası, roller veya jeton alanları hakkında garip hatalarla istekleri reddederse, compat anahtarlarının var olma nedeni budur. Önce supportsDeveloperRole: false denemesi yapın; eski OpenAI uyumlu uygulamalar developer rolünden önce gelir.
• Görsel modeller, barındırılan model görüntüleri desteklese bile input: [text, image] değerini açıkça belirtmelidir. dsh, aksi belirtilmedikçe özel modeller için yalnızca metin kabul eder.

Tarif 3: Yerleşik katalog sağlayıcıları

Ana akım bulutlar için özel bir bloğa ihtiyacınız yoktur. dsh, DeepSeek, Anthropic ve OpenAI için katalog sağlayıcıları ile birlikte gelir ve kurulum genellikle "bir API anahtarını yapıştır" şeklindedir. Özel katalog girişleri kendi yerel kimlik doğrulama akışlarına sahiptir: Bedrock AWS kimlik bilgilerini kullanır, Vertex bir ADC projesi ister, Azure kendi API sürümüne ihtiyaç duyar ve Codex OAuth aracılığıyla kimlik doğrulaması yapar.

Katalog sağlayıcıları, harness'ın arkasında yalnızca Claude veya GPT istediğinizde düşük sürtünmeli bir yoldur ve çoğu insanın DeepSeek V4-Pro'yu çalıştırma şekli budur, API'sinin Ağustos 2026'da piyasaya sürülmesi harness'ın kendisiyle birlikte geldi (ayrıntılar api-docs.deepseek.com adresinde). Özel sağlayıcılar, kataloğun kapsamadığı her şey içindir: yerel çalışma zamanları, ağ geçitleri, bölgesel satıcılar ve OpenAI uyumlu toplayıcılar.

Modeli seçme ve oturumların neyi hatırladığı

Bir sağlayıcı eklemek, modellerini kullanılabilir hale getirir; Ayarlar → Modeller'de bir model seçmek, onu yeni oturumlar için varsayılan yapar. Belgelerden içselleştirmeye değer iki davranış:

1. Mevcut oturumlar, başladıkları modeli korur. Oturumlar orijinal modellerini günlüğe kaydeder, bu nedenle proje ortasında varsayılanı değiştirmek geçmişi sessizce yeniden yazmaz veya devam eden bir oturumun ne kullandığını değiştirmez.
2. Mevcut varsayılanı içeren sağlayıcıyı silerseniz, besteci yeni bir model seçene kadar girişi engeller. Harness, tahmin etmek yerine yüksek sesle hata verir.

Bu oturum sabitlemesi tekrarlanabilirlik için önemlidir: dsh'yi diğer harness'larla karşılaştırırken (bunu tam olarak DeepSeek Harness Claude Kodu'na Karşı makalemizde yaptık), bir oturumun kaydının, çalışma ortasında bir değişiklik yerine tek bir modeli yansıttığına güvenebilirsiniz.

Yaygın hataların giderilmesi

Yanlış veya erişilemeyen baseURL. En yaygın hata, en az egzotik olanıdır. URL'nin protokolün beklediği yerde bittiğini (genellikle OpenAI uyumlu uç noktalar için /v1, DashScope için /compatible-mode/v1) ve basit bir GET {baseURL}/models isteğinin harness dışında başarılı olduğunu doğrulayın. Burası, Apidog İndir'in beş dakikada kendini amorti ettiği kontrol noktasıdır: isteği harness'ın göndereceği aynı başlıkla (Authorization: Bearer $KEY) gönderin ve sarılmış bir harness hatası yerine gerçek durum kodunu ve gövdeyi okuyun. Çevrimdışı geliştiriyorsanız veya satıcı güvenilmezse, Apidog'da sağlayıcının /models ve /chat/completions yanıtlarını sahteleyebilir ve geliştirme yaparken baseURL'i sahteleyicisine yönlendirebilirsiniz.

Eksik veya boş ortam değişkeni. apiKeyEnv bir değişkeni adlandırır; onu oluşturmaz. Değişken dsh'nin gerçekten çalıştığı ortamda ayarlanmamışsa, istekler kimlik doğrulanmamış olarak gider ve 401 döner. Bir GUI'den veya bir hizmet yöneticisinden başlatılan bir işlemin kabuk profilinizi miras almayabileceğini unutmayın. dsh web'i başlatan aynı bağlamda echo $GATEWAY_API_KEY komutunu çalıştırın, sadece rastgele bir terminalde değil.

Giriş modalitesi uyuşmazlığı. Bir görüntü ekliyorsunuz ve model bunu asla görmüyor veya istek hata veriyor. Özel modeller varsayılan olarak yalnızca metin tabanlıdır. Model girişine input: [text, image] ekleyin veya sağlayıcıdaki her model görüntüleri işliyorsa rota düzeyinde defaultInput ayarlayın.

Protokol tuhaflıkları. Desteklenmeyen bir rolü veya reddedilen bir jeton parametresini belirten hatalar, uyumluluk anahtarlarını işaret eder: supportsDeveloperRole: false ve maxTokensField: max_tokens belgelenmiş iki tanesidir.

Dün her şey çalışıyordu. Geliştirici önizlemesi. Dağıttığınız sürümü sabitleyin, yükseltmeden önce sürüm notlarını okuyun ve ayarlar şemasının değişebileceğini bekleyin. deepseek-harness deposu gerçek kaynağıdır, bu yazı dahil herhangi bir blog yazısı değil.

Bir entegrasyon notu daha: model sağlayıcıları, özelleştirme hikayesinin sadece yarısıdır. Diğer yarısı, aracının çağırabileceği araçlardır ve API iş akışlarınızı doğrudan bağlayabilirsiniz; bunu DeepSeek Harness içinde Apidog CLI kullanımı makalemizde ele alıyoruz.

SSS

DeepSeek Harness resmi olarak Ollama'yı destekliyor mu?

Resmi sağlayıcılar belgesi Ollama'dan adıyla bahsetmiyor. Desteklediği şey, openai-completions protokolünü konuşan herhangi bir uç noktadır ve Ollama, http://localhost:11434/v1 adresinde bir OpenAI uyumlu API belgeliyor. Yukarıdaki tarif, belgelenmiş iki yarımı birleştirir; dsh bir geliştirici önizlemesi olduğundan ve şemalar sürümler arasında değişebileceğinden, kurulumunuzda test edin.

dsh API anahtarlarımı nerede saklar?

$DSH_HOME/.credentials.yaml içinde, yalnızca yazılabilir olarak. UI, kaydettikten sonra sansürlenmiş bir tanımlayıcı gösterir ve settings.yaml yalnızca apiKeyEnv adları gibi referansları tutar. Sağlayıcı yapılandırmanızın içinde asla düz metin bir anahtar bulundurmazsınız.

Farklı oturumlar için farklı modeller çalıştırabilir miyim?

Evet. Bir model seçmek yalnızca yeni oturumlar için varsayılanı ayarlar; her mevcut oturum başladığı modeli korur. Böylece, rutin oturumlar için DeepSeek V4-Flash gibi ucuz bir model çalıştırabilir, zor bir sorun için varsayılanı daha ağır bir modele geçirebilirsiniz ve önceki oturumlarınız etkilenmez.

Özel uç noktam, curl'de aynı isteğin üretmediği hatalar döndürüyor. Şimdi ne olacak?

Tam yükleri karşılaştırın. Harness, arka ucunuzun kabul etmediği bir developer rolü veya daha yeni bir jeton-sınırı alanı gönderebilir; belgelenmiş düzeltmeler compat altında supportsDeveloperRole: false ve maxTokensField: max_tokens'dır. API istemcisinde harness'ın şekillendirdiği isteği yeniden oynatmak, arka ucun hangi alanda takıldığını size gösterecektir.