DEV Community

Cover image for DeepSeek Harness'ta Herhangi Bir Model Nasıl Çalıştırılır?
Tobias Hoffmann
Tobias Hoffmann

Posted on Originally published at apidog.com

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

DeepSeek Harness (dsh) kendi DeepSeek modelleriyle gelir; ancak yalnızca onlara bağlı değilsiniz. Harness, model sağlayıcılarını yapılandırılabilir bileşenler olarak ele alır: bir sağlayıcı bloğunu OpenAI uyumlu herhangi bir uç noktaya yönlendirin, kimlik bilgisi referansını tanımlayın ve aracı oturumlarınızı o URL’nin arkasındaki modelle çalıştırın. Yerel Ollama örnekleri, şirket içi ağ geçitleri, DashScope uyumlu modu üzerinden Qwen ve Anthropic veya OpenAI gibi katalog sağlayıcıları aynı yapı üzerinden kullanılabilir.

Apidog'u bugün deneyin

Bu kılavuzda sağlayıcı bloğunu anahtar anahtar inceleyecek, ardından üç uygulanabilir yapılandırma oluşturacaksınız: yerel model, barındırılan OpenAI uyumlu uç nokta ve yerleşik katalog sağlayıcıları. Buradaki bilgiler, master dalındaki resmi sağlayıcılar kılavuzundan alınmıştır ve 20 Ağustos 2026 tarihinde kontrol edilmiştir. dsh bir geliştirici önizlemesidir; README, uyumluluğu bozan değişiklikler olabileceği konusunda açıkça uyarır. Üretim yapılandırmasına geçmeden önce belgeleri kullandığınız sürümle karşılaştırın.

Harness’a yeniyseniz, önce DeepSeek Harness nedir ve nasıl çalışır? yazısını okuyun.

Bir aracı harness’ında neden model değiştirilir?

Bir aracı harness’ı şu döngüyle çalışır:

  1. Model plan yapar.
  2. Araç çağrıları üretir.
  3. Araç çıktıları bağlama eklenir.
  4. Model sonraki adımı belirler.

Harness bu döngüyü yönetir; model ise değiştirilebilir bir bileşendir. Model sağlayıcısını değiştirmenin üç pratik nedeni vardır:

  • Maliyet: Aracı oturumları, araç sonuçları sürekli bağlama eklendiği için hızla token tüketir. Rutin görevleri daha ekonomik bir modele veya DeepSeek V4-Pro yerine V4-Flash’a yönlendirebilirsiniz.
  • Veri yerelliği: Kod tabanınız ağ dışına çıkmamalıysa, kendi donanımınızda çalışan bir modele bağlanın. İstemler, dosya içerikleri ve araç çıktıları yerel ortamda kalır.
  • Yerel geliştirme: Eklenti geliştirirken ya da araç davranışını test ederken her iterasyonda API kredisi tüketmek istemeyebilirsiniz. Küçük bir yerel model, döngüyü test etmek için yeterlidir.

Bu esneklik, dsh mimarisinden gelir: harness içindeki her şey eklentidir ve model adaptörü de değiştirilebilir parçalardan biridir. Sağlayıcı rotaları, dsh-llm-pi-ai eklentisinin yapılandırmasında tutulur. Kullanıcı tarafındaki yapılandırma yüzeyi ise YAML bloğudur.

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

Özel sağlayıcıları $DSH_HOME/settings.yaml dosyasında tanımlayabilir veya web arayüzünde Ayarlar → Modeller üzerinden ekleyebilirsiniz.

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

Bu yapılandırmadaki alanların işlevi:

  • my-gateway: Sağlayıcı kimliğidir. Kalıcı ve anlamlı bir ad seçin. Arayüzde gösterilen görünen ad ayrı olarak ayarlanabilir.
  • apiKeyEnv: API anahtarını içeren ortam değişkeninin adıdır. Ayar dosyası anahtarın kendisini değil, yalnızca referansını içerir.
  • api: İletişim protokolünü belirler. OpenAI uyumlu uç noktalar için belgelenen değer openai-completions’tır.
  • baseURL: Harness’ın istek göndereceği uç nokta köküdür.
  • models: Sağlayıcı üzerinden kullanılabilecek model kimliklerini listeler. Her kayıt en az bir id içermelidir.
  • input: Modelin desteklediği giriş türlerini bildirir. Özel modeller varsayılan olarak yalnızca metin kabul eder. Görsel model kullanıyorsanız input: [text, image] eklemelisiniz.
  • defaultInput: Sağlayıcıdaki tüm modeller için varsayılan giriş türünü belirler. Model seviyesindeki input alanı bunu geçersiz kılar.
  • compat: Varsayılan OpenAI davranışından farklı çalışan uç noktalar için uyumluluk seçeneklerini içerir.

Belgelenen uyumluluk seçenekleri:

compat:
  supportsDeveloperRole: false
  maxTokensField: max_tokens
Enter fullscreen mode Exit fullscreen mode
  • supportsDeveloperRole: false: developer rolünü kabul etmeyen arka uçlar için kullanılır.
  • maxTokensField: max_tokens: Eski token sınırı alan adını bekleyen uç noktalar için kullanılır.

Web arayüzünden özel sağlayıcı eklerken Kullanılabilir modelleri getir seçeneğini kullanabilirsiniz. Bu seçenek, OpenAI uyumlu GET /models uç noktasını çağırır ve model listesini otomatik doldurur.

API anahtarları nerede saklanır?

Sırlar yalnızca yazılabilir biçimde $DSH_HOME/.credentials.yaml içinde saklanır. Bir anahtarı UI üzerinden kaydettikten sonra dsh yalnızca sansürlenmiş tanımlayıcıyı gösterir; gerçek değer tekrar gösterilmez.

Özetle:

  • settings.yaml: Sağlayıcı yapılandırması ve referanslar
  • .credentials.yaml: Gizli anahtarlar
  • apiKeyEnv: Ortam değişkeni adı

Bu ayrım sayesinde ayar dosyasını sırları sızdırmadan paylaşabilir veya sürüm kontrolüne ekleyebilirsiniz.

Tarif 1: Ollama ile yerel model çalıştırma

Ollama, http://localhost:11434/v1 adresinde OpenAI uyumlu bir API sunar. Bu davranış, Ollama’nın OpenAI uyumluluk kılavuzunda belgelenmiştir.

Önce yerel modeli indirin:

ollama pull gpt-oss:20b
Enter fullscreen mode Exit fullscreen mode

Ardından modelin listede göründüğünü doğrulayın:

ollama list
Enter fullscreen mode Exit fullscreen mode

dsh yapılandırmasını ekleyin:

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

Ollama yerel kullanımda API anahtarı gerektirmez. Ancak şema bir kimlik bilgisi referansı beklediği için yerel bir placeholder değer tanımlayın:

export OLLAMA_API_KEY=ollama
Enter fullscreen mode Exit fullscreen mode

Dikkat edilmesi gerekenler:

  • Model id değeri, ollama list çıktısındaki adla tam olarak eşleşmelidir.
  • Etiketleri de dahil edin: örneğin gpt-oss:20b.
  • dsh’ye bağlamadan önce Ollama sunucusunun çalıştığını doğrulayın.

Yerel kurulumu doğrulamak için önce /models çağrısını doğrudan test edin:

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

Alternatif olarak Apidog ile şu isteği gönderin:

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

İstek model listesini döndürüyorsa:

  • baseURL doğrudur,
  • Ollama çalışıyordur,
  • dsh içindeki Kullanılabilir modelleri getir işlevi de çalışmalıdır.

Ollama ile GPT-OSS çalıştırma adımlarını daha ayrıntılı olarak Ollama kullanarak GPT-OSS nasıl çalıştırılır yazısında bulabilirsiniz.

Not: Resmi dsh belgeleri Ollama’ya özel örnek vermiyor. Bu yapılandırma, dsh’nin belgelenmiş özel sağlayıcı şemasını Ollama’nın belgelenmiş OpenAI uyumlu uç noktasına uygular. Üretimde kullanmadan önce kendi ortamınızda test edin.

Küçük yerel modeller eklenti geliştirme ve araç döngüsü testi için faydalıdır. Ancak karmaşık planlama, uzun bağlam ve yoğun araç çağırma işlerinde öncü modellerden daha düşük performans gösterebilirler.

Tarif 2: DashScope üzerinden barındırılan Qwen uç noktası

Barındırılan sağlayıcı kullanırken yalnızca OpenAI uyumluluğunu açıkça belgeleyen uç noktaları tercih edin. Alibaba Cloud Model Studio (DashScope), Qwen modelleri için OpenAI uyumlu bir uç nokta sağlar.

DashScope’un OpenAI uyumluluk sayfası, aşağıdaki biçimde bir uç nokta belgeler:

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

dsh yapılandırması:

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

Kurulum adımları:

  1. Model Studio konsolundan gerçek çalışma alanı kimliğinizi alın.
  2. {WorkspaceId} değerini uç noktada değiştirin.
  3. API anahtarını ortam değişkeni olarak ekleyin. 
export DASHSCOPE_API_KEY=your_api_key
Enter fullscreen mode Exit fullscreen mode
  1. Kullanılabilir model kimliklerini satıcının güncel model listesinden doğrulayın.
  2. dsh arayüzünden sağlayıcıyı ekleyin ve model seçin.

Qwen model ailesi hakkında ek bilgi için Qwen 3.8 API kılavuzuna bakabilirsiniz.

Bu desen yalnızca DashScope’a özel değildir. Belgelenmiş OpenAI uyumluluğu olan diğer uç noktalarda da aynı yapı kullanılır:

  • Moonshot Kimi API
  • OpenRouter
  • vLLM dağıtımları
  • Kurum içi API ağ geçitleri

Genellikle yalnızca şu alanları değiştirmeniz gerekir:

apiKeyEnv: YOUR_PROVIDER_API_KEY
baseURL: https://provider.example/v1
models:
  - id: provider-model-id
Enter fullscreen mode Exit fullscreen mode

Codex’te açık kaynak modelleri yapılandırdıysanız, bu desen tanıdık gelecektir. dsh’deki sağlayıcı bloğu, Codex’teki model_providers yapılandırmasına benzer bir rol üstlenir.

Barındırılan uç noktalarda iki yaygın ayrıntı vardır:

  1. Uç nokta rol veya token alanı hatası döndürüyorsa compat ayarını deneyin: 
   compat:
     supportsDeveloperRole: false
Enter fullscreen mode Exit fullscreen mode
  1. Görsel model kullanıyorsanız görüntü girişini açıkça bildirin: 
   models:
     - id: qwen-vision-model
       input: [text, image]
Enter fullscreen mode Exit fullscreen mode

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

DeepSeek, Anthropic ve OpenAI gibi yaygın bulut sağlayıcıları için özel sağlayıcı bloğu oluşturmanız gerekmez. dsh, bu sağlayıcılar için katalog girişleriyle birlikte gelir.

Kurulum genellikle API anahtarını eklemekten ibarettir. Ancak bazı sağlayıcılar kendi kimlik doğrulama akışlarını kullanır:

Sağlayıcı Kimlik doğrulama yaklaşımı
Bedrock AWS kimlik bilgileri
Vertex ADC projesi
Azure API sürümü ve Azure yapılandırması
Codex OAuth

Katalog sağlayıcıları, yalnızca Claude, GPT veya DeepSeek modellerini kullanmak istiyorsanız en düşük sürtünmeli yoldur. DeepSeek V4-Pro gibi modeller için bu genellikle varsayılan yaklaşımdır. API ayrıntıları için api-docs.deepseek.com adresini kontrol edin.

Özel sağlayıcılar ise katalog dışında kalan senaryolar içindir:

  • Yerel model çalışma zamanları
  • Şirket içi ağ geçitleri
  • Bölgesel sağlayıcılar
  • OpenAI uyumlu model toplayıcıları

Model seçimi ve oturum davranışı

Bir sağlayıcı eklemek, modellerini kullanılabilir hale getirir. Ayarlar → Modeller bölümünden model seçmek ise onu yeni oturumların varsayılanı yapar.

İki önemli davranış:

  1. Mevcut oturumlar başladıkları modeli korur.

    Varsayılan modeli değiştirmeniz, devam eden veya önceki oturumların modelini değiştirmez.

  2. Varsayılan modeli kaldırırsanız giriş engellenir.

    Mevcut varsayılanı içeren sağlayıcıyı silerseniz, yeni model seçene kadar besteci girişi kabul etmez.

Bu davranış tekrarlanabilirlik açısından önemlidir. Bir oturumun kaydı, çalışma sırasında model değişmiş gibi görünmez. DeepSeek Harness ile diğer araçları karşılaştırırken bu farkı özellikle dikkate alın; örnek karşılaştırma için DeepSeek Harness vs Claude Code yazısına bakabilirsiniz.

Yaygın hataları giderme

Yanlış veya erişilemeyen baseURL

En sık karşılaşılan sorun budur. URL’nin beklenen kökte bittiğini doğrulayın:

  • Çoğu OpenAI uyumlu uç nokta: /v1
  • DashScope: /compatible-mode/v1

dsh yapılandırmasını değiştirmeden önce şu isteği çalıştırın:

curl -H "Authorization: Bearer $GATEWAY_API_KEY" \
  https://gateway.example/v1/models
Enter fullscreen mode Exit fullscreen mode

İstek başarısızsa sorun harness yapılandırması değil, uç nokta veya kimlik doğrulamasıdır.

Apidog’u indirin ve aynı isteği harness’ın göndereceği başlıklarla test edin:

Authorization: Bearer YOUR_API_KEY
Enter fullscreen mode Exit fullscreen mode

Bu şekilde yalnızca sarmalanmış harness hatasını değil, gerçek HTTP durum kodunu ve yanıt gövdesini de görürsünüz.

Çevrimdışı geliştirme yapıyorsanız veya sağlayıcı kararsızsa, Apidog’da şu uç noktaları mock’layabilirsiniz:

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

Ardından baseURL değerini mock sunucunuza yönlendirin.

Eksik veya boş ortam değişkeni

apiKeyEnv yalnızca bir değişken adı belirtir; değişkeni oluşturmaz.

Örneğin:

apiKeyEnv: GATEWAY_API_KEY
Enter fullscreen mode Exit fullscreen mode

Bu durumda dsh’nin çalıştığı ortamda şu değişken tanımlı olmalıdır:

export GATEWAY_API_KEY=your_api_key
Enter fullscreen mode Exit fullscreen mode

Kontrolü, dsh web komutunu başlattığınız aynı bağlamda yapın:

echo $GATEWAY_API_KEY
Enter fullscreen mode Exit fullscreen mode

GUI veya hizmet yöneticisi üzerinden başlatılan süreçlerin kabuk profilinizdeki değişkenleri devralmayabileceğini unutmayın.

Giriş modalitesi uyuşmazlığı

Görüntü ekliyor ancak model görüntüyü görmüyorsa, model giriş türünü açıkça tanımlayın:

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

Sağlayıcıdaki tüm modeller görsel destekliyorsa rota düzeyinde varsayılan da tanımlayabilirsiniz:

llm-pi-ai:
  providers:
    my-provider:
      defaultInput: [text, image]
Enter fullscreen mode Exit fullscreen mode

Protokol uyumluluğu sorunları

Arka uç, desteklenmeyen rol veya token parametresi nedeniyle istekleri reddediyorsa aşağıdaki ayarları kullanın:

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

“Dün çalışıyordu” sorunu

dsh bir geliştirici önizlemesidir. Bu nedenle:

  1. Kullandığınız sürümü sabitleyin.
  2. Yükseltmeden önce sürüm notlarını okuyun.
  3. Ayar şemasının değişebileceğini varsayın.
  4. Son doğrulama kaynağı olarak deepseek-harness deposunu kullanın.

Model sağlayıcıları özelleştirme hikâyesinin yalnızca yarısıdır. Diğer yarısı, aracının çağırabileceği araçları yapılandırmaktır. API iş akışlarını doğrudan bağlamak için DeepSeek Harness içinde Apidog CLI kullanımı yazısına göz atın.

SSS

DeepSeek Harness resmi olarak Ollama’yı destekliyor mu?

Resmi sağlayıcı belgesi Ollama’dan adıyla bahsetmez. Ancak openai-completions protokolünü konuşan herhangi bir uç noktayı destekler. Ollama da http://localhost:11434/v1 adresinde OpenAI uyumlu API sunar.

Bu nedenle yukarıdaki yapılandırma, belgelenmiş iki uyumlu parçayı birleştirir. dsh geliştirici önizlemesi olduğundan, üretimde kullanmadan önce kendi sürümünüzde test edin.

dsh API anahtarlarını nerede saklar?

API anahtarları yalnızca yazılabilir olarak şu dosyada saklanır:

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

settings.yaml dosyası yalnızca apiKeyEnv gibi referansları içerir. Sağlayıcı yapılandırmasında düz metin API anahtarı tutmayın.

Farklı oturumlarda farklı modeller kullanabilir miyim?

Evet. Model seçimi yalnızca yeni oturumların varsayılanını değiştirir. Mevcut oturumlar başladıkları modeli korur.

Örneğin, rutin işler için DeepSeek V4-Flash gibi daha ekonomik bir model kullanabilir; zor görevlerde varsayılanı daha güçlü bir modele değiştirebilirsiniz. Önceki oturumlarınız etkilenmez.

Özel uç noktam, curl ile çalışmasına rağmen dsh’de hata veriyor. Ne yapmalıyım?

Tam istek gövdelerini karşılaştırın. Harness, arka ucunuzun kabul etmediği bir developer rolü veya yeni token sınırı alanı gönderiyor olabilir.

Önce şu uyumluluk ayarlarını deneyin:

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

Ardından harness’ın gönderdiği isteği bir API istemcisinde yeniden üretin. Böylece arka ucun hangi alan veya başlıkta hata verdiğini doğrudan görebilirsiniz.

Top comments (0)