Temel noktalar
- OpenCode'u düzenlemeden önce uç noktayı curl ile doğrulayın; böylece bir hatanın yapılandırmadan mı yoksa API'den mi kaynaklandığını anlayabilirsiniz.
- Özel bir sağlayıcı için üç şeye ihtiyacınız vardır: base URL, API anahtarı ve burada uncensored olan bir model ID.
- Ajanın gerçek pencereyi göz önünde bulundurması için bağlam sınırını 100.000 token olarak ayarlayın.
- Akış ve fonksiyon çağırma desteklenir; bu bir agent döngüsü için gereklidir.
Başlamadan önce ihtiyacınız olanlar
OpenCode, terminalinizde çalışan açık kaynaklı bir kodlama ajanıdır. Birçok model sağlayıcısıyla iletişim kurabilir ve uç nokta OpenAI sohbet formatını takip ediyorsa kendi sağlayıcınızı eklemenizi sağlar. Bu API bu formatı kullandığından, kurulum birkaç alanı doldurmaktan ibarettir.
Önce bu üç değeri edinin:
- Base URL:
https://api.kimicode.top/v1 - Model Kimliği:
uncensored - API anahtarı: API anahtarı sayfasında bir tane oluşturun. Yeni hesaplar tek tıkla $0.50 deneme kredisi alabilir; bu aşağıdaki testler için yeterlidir. Deneme anahtarı 2 eşzamanlı istek ve dakikada 60 istek izni verir.
Anahtarı dosyalara yapıştırmak yerine bir ortam değişkeninde tutun:
export KIMICODE_API_KEY="your-key-here"Adım 1: uç noktayı curl ile test etme
Bu işlemi herhangi bir aracı yapılandırmadan önce yapın. Eğer curl çalışır ama OpenCode çalışmazsa, sorunun yapılandırmada olduğunu anlarsınız. Eğer curl başarısız olursa, anahtarı veya URL'i iki yerde değil, bir kez düzeltirsiniz.
curl https://api.kimicode.top/v1/chat/completions \
-H "Authorization: Bearer $KIMICODE_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "uncensored",
"messages": [{"role": "user", "content": "Say hello in five words."}],
"max_tokens": 40
}'Bir choices dizisi ve bir usage bloğu içeren bir JSON nesnesi almalısınız. 401 hatası anahtarın yanlış olduğunu veya Bearer önekini içermediğini gösterir. 404 hatası genellikle URL'in yanlış yazıldığını veya zaten /chat/completions içerdiğini gösterir.
Bir kodlama ajanı yanıtlarını akış olarak gönderir ve araçları çağırır, bu yüzden bu iki özelliği de kontrol edin:
curl -N https://api.kimicode.top/v1/chat/completions \
-H "Authorization: Bearer $KIMICODE_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "uncensored",
"stream": true,
"messages": [{"role": "user", "content": "Count from one to five."}]
}'Küçük bir JSON delta içeren, kullanım istatistikleri ve bir son işaretleyici ile biten bir dizi data: satırı görmelisiniz. -N bayrağı, curl'ün arabelleğe almasını devre dışı bırakır, böylece parçalar geldikçe görünür.
Adım 2: OpenCode'a özel sağlayıcı ekleme
OpenCode, projenizin klasöründen veya genel yapılandırma dizininden opencode.json adlı bir JSON yapılandırma dosyası okur. Özel OpenAI tarzı sağlayıcılar, AI SDK'sının OpenAI uyumlu paketi, bir base URL ve bir model listesi ile tanımlanır. Aşağıdaki düzen, yazım anında OpenCode'un genel belgelerine uygundur. Sürümler arasında alan adları değişebileceğinden, bir şey reddedilirse geçerli OpenCode belgelerinin sağlayıcı bölümüyle karşılaştırın.
{
"$schema": "https://opencode.ai/config.json",
"provider": {
"kimicode": {
"npm": "@ai-sdk/openai-compatible",
"name": "Kimicode API",
"options": {
"baseURL": "https://api.kimicode.top/v1",
"apiKey": "{env:KIMICODE_API_KEY}"
},
"models": {
"uncensored": {
"name": "Uncensored",
"limit": {
"context": 100000,
"output": 8192
}
}
}
}
},
"model": "kimicode/uncensored"
}models altındaki anahtar, sunucuya gönderilen tam model ID'sidir, bu nedenle uncensored olarak okunmalıdır. Son satır, sağlayıcıyı ve modeli varsayılan olarak seçer, sağlayıcı adı, bir slash, ardından model ID olarak yazılır.
{env:KIMICODE_API_KEY} biçimi, OpenCode'un değişkeni kabuktan okumasını sağlar. Sürümünüz kimlik bilgilerini kendi giriş komutu aracılığıyla yönetiyorsa, bu yolu kullanın ve anahtarı dosyadan çıkarın. Her iki durumda da gerçek bir anahtarı kaynağa eklemeyin.
Proje yapılandırması veya global yapılandırma
Sağlayıcı bloğunu iki yerde tutabilirsiniz. Proje kökündeki bir dosya yalnızca o depoyu etkiler ve tek bir kurulumu paylaşan bir ekip için uygundur. Kullanıcı yapılandırma dizinindeki bir dosya her yerde geçerlidir ve kişisel bir varsayılan için uygundur. İkisi de varsa, proje dosyası global olanı genişletir veya geçersiz kılar.
Sağlayıcı tanımı için genel dosyayı ve anahtar için ortam değişkenini tercih edin. Böylece her depo uç noktasını kullanabilir ve kaynak kodunuzun yanında gizli bir şey kalmaz. Birden fazla kişi aynı projede çalışıyorsa, anahtarsız sağlayıcı bloğunu kaynağa ekleyin ve her kişinin kendi değişkenini ayarlamasını sağlayın. Bu, bir anahtarı değiştirmeyi de basitleştirir: değişkeni değiştirin, terminali yeniden başlatın ve yapılandırma dosyası dokunulmaz kalır.
Adım 3: modeli seçme ve görev çalıştırma
OpenCode'u bir proje klasöründe başlatın ve model seçicisini açın. Özel sağlayıcınız, ayarladığınız gösterim adıyla listede görünmelidir. Bunu seçin ve ajana küçük, kontrol edilebilir bir görev verin; örneğin bir fonksiyonu açıklamak veya kısa bir dosya için birim test yazmak.
İki nedenle küçük başlayın. Birincisi, araç çağrılarının çalışıp çalışmadığını görebilirsiniz: OpenCode modelden bir dosya okumasını veya düzenlemesini istediğinde, bunu araç çağırma arayüzü aracılığıyla yapar. İkincisi, bir kodlama ajanı her adımda dosya içerikleri ve geçmiş dahil olmak üzere çok fazla metin gönderir, bu yüzden uzun bir oturum tokenları hızla tüketir. Bir sonraki bölümde bu sayılarla ilgili örnekler yer almaktadır.
Model görünmüyorsa, dosyanın geçerli JSON olup olmadığını, OpenCode'un yapılandırma dosyalarını aradığı konumda olup olmadığını ve sağlayıcı adının model alanında yazdığınız şeyle eşleşip eşleşmediğini kontrol edin.
Fonksiyon çağırma ve JSON modunu doğrudan test etme
OpenCode, dosyaları okumak, komutları çalıştırmak ve kodu düzenlemek için araç çağırma kullanır, bu yüzden ajanı bir hatada suçlamadan önce uç noktanın bir araç tanımını işleyip işlemediğini doğrulamaya değer. Bu istek bir araç sunar ve bunun gerektiği bir soru sorar.
curl https://api.kimicode.top/v1/chat/completions \
-H "Authorization: Bearer $KIMICODE_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "uncensored",
"messages": [{"role": "user", "content": "What is in the file notes.txt?"}],
"tools": [{
"type": "function",
"function": {
"name": "read_file",
"description": "Read a text file by path",
"parameters": {
"type": "object",
"properties": {"path": {"type": "string"}},
"required": ["path"]
}
}
}],
"tool_choice": "auto"
}'İyi bir yanıt, tool_calls girişini içeren ve read_file adlı bir JSON argüman dizesi belirten bir yapıdır. Ajan aracı çalıştırır, ardından sonucu role değeri tool olarak ayarlanmış bir mesaj olarak gönderir ve model oradan devam eder. Yalnızca düz metin görürseniz, modelin bir aracı kullanmaya karar verip vermemesi davranışının bir parçası olduğundan daha doğrudan bir istem deneyin.
JSON modu ayrı bir anahtardır. "response_format": {"type": "json_object"} eklemek geçerli JSON çıktısı ister ve başka bir betiğin gelen veriyi ayrıştırması gerektiğinde yardımcı olur. Modelin ne beklediğinizi bilmesi için isteminize JSON'u da ekleyin.
Bağlam boyutu ve oturum maliyeti
Bağlam penceresi, istem ve tamamlama birlikte 100.000 token'dır. limit.context değerini 100000 olarak ayarlamak, aracıya gerçek tavanı bildirmesini sağlar, böylece sunucunun bir isteği reddetmesinden önce geçmişi kısaltabilir veya özetleyebilir. Bir tamamlama kalan her şeyi kullanabilir ve max_tokens isteğe bağlıdır.
Faturalandırma, 1M giriş token'ı başına $0.15 ve 1M çıktı token'ı başına $0.50'dir. Ajanlar giriş ağırlıklıdır, çünkü her adım konuşmayı yeniden gönderir. Orta düzey bir oturum için bir örnek:
- 40 adım, her biri yaklaşık 30,000 giriş token'ı gönderir: 1,200,000 giriş token'ı, bu da 1.2 x $0.15 = $0.18 eder.
- Her adım yaklaşık 800 çıktı token'ı döndürür: 32,000 çıktı token'ı, bu da 0.032 x $0.50 = $0.016 eder.
- Toplam: $0.196, yani tüm oturum için yaklaşık yirmi sent.
Sayılarınız farklı olacaktır. Yanıtlardaki usage değerlerini okuyun veya her yanıtta kalan bakiyenizi bildiren X-Balance-USD üst bilgisini izleyin. Kredi ön ödemelidir ve asla sona ermez, başarısız veya reddedilen istekler için ücret alınmaz. Ayrıntılar fiyatlandırma sayfasında yer almaktadır.
Bir kodlama agent'ı için dürüst beklentiler
Bu, yasal yetişkin kullanımı için içerik reddi olmadan yanıt verecek şekilde ayarlanmış genel bir metin modelidir. Kod için özel olarak inşa edilmiş bir model değildir ve bu sayfa herhangi bir benchmark iddiası taşımaz. Depoyu güvenilir şekilde düzenleyip düzenleyemeyeceği, önemli bir şey vermeden önce kendi görevlerinizde, sürüm kontrolü açıkken test etmeniz gereken bir konudur.
Bir ajanın ihtiyaç duyduğu altyapıyı yönetir: akışlı tool_calls ile araç çağırma, role: "tool" mesajları olarak gönderilen araç sonuçları ve response_format aracılığıyla JSON modu. Sadece metindir, resim yoktur, bu nedenle ekran görüntüsü ekleyen özellikler çalışmaz.
Aracılar için iki sınır önemlidir. Tam anahtar 8 eşzamanlı istek ve dakika başına 300 istek izni verir. Aynı anda çok sayıda çağrı tetikleyen alt aracılar veya paralel araç çalıştırmaları eşzamanlılık sınırına takılabilir ve akışlı bir istek, akış bitene kadar slotunu korur. Bu durumda concurrency koduyla HTTP 429 alırsınız. rate_limited kodu, dakika başına çok fazla istek yapıldığını gösterir. Geçici aşırı yüklenme durumunda Retry-After: 5 ile birlikte 429 da görebilirsiniz. Paralelliği azaltın veya bekleyip yeniden deneyin.
Sorun Giderme
| Belirti | Olası neden | Çözüm |
|---|---|---|
| 401 Yetkisiz | Boş veya yanlış anahtar; OpenCode'u başlatan kabukta ortam değişkeni ayarlanmamış | Aynı terminalde echo $KIMICODE_API_KEY çalıştırın, ardından OpenCode'u yeniden başlatın |
| 404 Bulunamadı | Base URL /chat/completions içeriyor veya /v1 eksik | Tam olarak https://api.kimicode.top/v1 kullanın |
| Model bulunamadı | Model anahtarı uncensored ile farklı | models içindeki anahtarı, GET /v1/models tarafından döndürülen kimlikle eşleştirin |
concurrency ile 429 | Aynı anda çok fazla istek | Daha az eşzamanlı fonksiyon çağırma veya akışların bitmesini bekleyin |
| İstek çok büyük | 8 MB'ı aşan gövde veya pencere sınırına yakın geçmiş | Yeni bir oturum başlatın veya geçmişi özetleyin |
Burada kapsanmayan her şey için dokümantasyon sayfası tam istek referansını içerir ve entegrasyon kılavuzu aynı uç nokta için diğer OpenAI tarzı istemciler açısından kapsar.
