Yaygın çerçevelerde aracı API yapılandırma: SDK'dan Dify'a

Önce üç değeri hazırlayın

Hangi çerçeveyi kullanırsanız kullanın, önce bu üç şeye sahip olduğunuzdan emin olun; geri kalanı sadece doldurulacak alanlardır.

• Uç nokta adresi: https://api.llmzhongzhuan.com/v1. Sonundaki /v1'i koruyun ancak /chat/completions'i tekrar eklemeyin; SDK bunu otomatik olarak birleştirir.
• Anahtar: Anahtar Alma Sayfası'nde e-posta ve şifre ile kaydolduktan sonra hemen görünür. Her hesap için bir anahtar vardır; sıfırlanırsa eski anahtar hemen geçersiz olur.
• Model adı: Yalnızca biri vardır, uncensored. Kendiniz GET /v1/models ile doğrulayabilirsiniz.

Ayrıca şu sınırları da unutmayın: Toplam bağlam penceresi 100,000 token'dır. Tek istekte max_tokens varsayılan olarak 2048, maksimum 32,000'dir. Her API anahtarı için dakikada 300 istek hız limiti vardır. Bu sayılar sonraki parametre ayarlarında sıkça kullanılacaktır.

Ortam değişkenlerinin yazımı

Anahtarı koda sabit yazmak en yaygın hata kaynağıdır. Önerilen yöntem yalnızca ortam değişkenlerini okumaktır; dağıtım sırasında anahtarı kapsayıcı veya anahtar yönetim sistemi enjekte eder. Aşağıda API_KEY ve API_BASE değişkenlerini kullanacağız; tüm çerçeveler bu isimleri kullanır.

复制# Linux / macOS：写进 ~/.zshrc 或 .env 加载脚本
export API_KEY="替换为你的密钥"
export API_BASE="https://api.llmzhongzhuan.com/v1"

# Windows PowerShell（仅当前会话）
$env:API_KEY = "替换为你的密钥"
$env:API_BASE = "https://api.llmzhongzhuan.com/v1"

.env dosyası kullanıyorsanız, onu .gitignore dosyasına eklemeyi unutmayın. Ayrıca, resmi Python SDK'sı varsayılan olarak OPENAI_API_KEY ve OPENAI_BASE_URL'i okur. Bu değişken isimlerini kullanabilir veya aşağıdaki gibi yapılandırıcıda açıkça parametre geçirebilirsiniz. Açık geçirme, makinedeki eski değişkenlerle çakışmayı önler ve hata ayıklamayı kolaylaştırır.

OpenAI Python SDK ve Node SDK

Python için v1 üstü openai paketi, Node için v4 üstü gereklidir. Aralarındaki fark yalnızca sözdizimidir; adres ve anahtarı istemci oluştururken geçirmeniz yeterlidir. Önce Python ile akış olmayan bir çağrı yapalım ve kullanım bilgisini yazdırarak ücretlendirmeyi doğrulayalım:

复制import os
from openai import OpenAI

client = OpenAI(
    base_url=os.environ.get("API_BASE", "https://api.llmzhongzhuan.com/v1"),
    api_key=os.environ["API_KEY"],
)

resp = client.chat.completions.create(
    model="uncensored",
    messages=[{"role": "user", "content": "写一条 20 字以内的发布公告标题。"}],
    max_tokens=100,
)
print(resp.choices[0].message.content)
print(resp.usage)

Node örneği akışlı çıktı kullanır; bu, ön uçta daktilo efekti için en yaygın yazımdır. Akış isteği bittiğinde sunucu, kullanım bilgisi içeren bir parça ekler; ek parametre gerekmez:

复制import OpenAI from "openai";

const client = new OpenAI({
  baseURL: process.env.API_BASE ?? "https://api.llmzhongzhuan.com/v1",
  apiKey: process.env.API_KEY,
});

const stream = await client.chat.completions.create({
  model: "uncensored",
  messages: [{ role: "user", content: "列出三个命名服务端日志字段的好习惯。" }],
  stream: true,
  max_tokens: 300,
});

for await (const chunk of stream) {
  process.stdout.write(chunk.choices[0]?.delta?.content ?? "");
}
process.stdout.write("\n");

Node örneği üst düzey await kullanır; bu .mjs dosyası veya package.json'da "type": "module" ayarı gerektirir. Çalışma ortamınız desteklemiyorsa, kodu bir async fonksiyonun içine alın.

LangChain: ChatOpenAI'nin base_url'i

LangChain'de özel bir adaptöre gerek yoktur; langchain_openai paketindeki ChatOpenAI sınıfını kullanın ve base_url'i ona işaret edin.

复制import os
from langchain_openai import ChatOpenAI

llm = ChatOpenAI(
    model="uncensored",
    base_url=os.environ.get("API_BASE", "https://api.llmzhongzhuan.com/v1"),
    api_key=os.environ["API_KEY"],
    temperature=0.7,
    max_tokens=500,
    timeout=60,
)

print(llm.invoke("把“服务已降级”改写成对用户友好的一句话。").content)

İki küçük uyarı. Birincisi, max_tokens ve timeout'i açıkça ayarlayın; varsayılan değerler iş gereksinimlerinize uygun olmayabilir. İkincisi, zincir içinde fonksiyon çağırma kullanıyorsanız, sitemiz OpenAI formatında tools destekler; LangChain'in bind_tools'i düzgün çalışır. Akış modunda stream() içinde parça parça tüketin.

LlamaIndex: OpenAILike

LlamaIndex'in yerleşik OpenAI sınıfı model adının resmi listede olup olmadığını doğrular; özel adlar hata verir. Bu durumda llama-index-llms-openai-like paketindeki OpenAILike sınıfını kullanın; bu sınıf doğrulama yapmaz ve parametre isimleri farklıdır: adres api_base olarak adlandırılır.

复制import os
from llama_index.llms.openai_like import OpenAILike

llm = OpenAILike(
    model="uncensored",
    api_base=os.environ.get("API_BASE", "https://api.llmzhongzhuan.com/v1"),
    api_key=os.environ["API_KEY"],
    is_chat_model=True,
    context_window=100000,
    max_tokens=500,
)

print(llm.complete("用一句话解释什么是幂等请求。"))

Burada is_chat_model=True çok önemlidir; LlamaIndex'i eski tamamlama yerine sohbet uç noktasına yönlendirir. context_window'i 100000 olarak ayarlayın; böylece LlamaIndex bağlamı bölerken varsayılan binlerce token ile belgelerinizi erken kesmez.

Dify: OpenAI-API-compatible sağlayıcısı

Dify gibi görsel platformlar kod içermez; form üzerinden yapılandırma yapılır. Arayüz metinleri sürümlere göre hafifçe farklılık gösterebilir ancak adımlar temelde aynıdır:

1. "Ayarlar" bölümüne gidin, "Model Sağlayıcıları" sayfasını bulun ve listede "OpenAI-API-compatible" seçeneğini belirleyip model ekleyin.
2. Model türü olarak "LLM" seçin, model adı olarak uncensored girin.
3. API Key alanına anahtarınızı, API endpoint URL alanına ise https://api.llmzhongzhuan.com/v1 adresini girin.
4. Model bağlam uzunluğu olarak 100000, maksimum token sınırı olarak 32000 girin.
5. İş akışında fonksiyon çağırma kullanacaksanız fonksiyon çağırma desteğini açın; akışlı çıktıyı açık bırakın.
6. Kaydettikten sonra basit bir sohbet uygulaması oluşturun, az önce eklediğiniz modeli seçin ve bir mesaj göndererek yanıt alabildiğinizi doğrulayın.

Platform bazen kaydetme sırasında bir keşif isteği gönderir. Bu adım başarısız olursa genellikle adreste fazladan yol yazılmıştır veya anahtarın başında/sonunda boşluk vardır. Dify'ı bir kapsayıcıda çalıştırıyorsanız, kapsayıcının dış etki alan adlarına erişebildiğinden emin olun.

Yayınlamadan önce doğrulanması gereken parametreler ve dağıtım yazımı

Çerçevenin çalışması ilk adımdır; aşağıdaki parametreleri yayınlamadan önce tek tek doğrulayın; bunlar maliyet ve hata oranlarını belirler.

• max_tokens: Varsayılan 2048'tir; uzun metin çıktısı için açıkça artırın, üst sınır 32,000'dir. Giriş ve çıktı toplamı 100,000'i geçerse 400 hatası alırsınız.
• timeout: Uzun çıktılı istekler daha uzun sürer; akış senaryolarında okuma zaman aşımını 60 saniyenin üzerine ayarlayın, akış olmayan durumlarda ise en uzun çıktıya göre tahmin edin.
• temperature / top_p / stop: Bu standart örnekleme parametreleri doğrudan geçirilir; çerçevelerde ayarlanan değerler doğrudan geçerli olur, ek bir anahtara gerek yoktur.
• Eşzamanlı istekler: Her API anahtarı için dakika başına 300 istek. Aynı anahtarı birden fazla hizmet örneği paylaştığında hız limiti birleştirilerek hesaplanır; her örneği 300 istek olarak planlamayın.
• Yeniden deneme: Çerçevelerin kendi yeniden deneme mekanizmaları genellikle yalnızca ağ hataları içindir; 429 ve 503 hataları için geri çekilme eklemeniz gerekir. Yöntem için stabilite makalesine bakın.

Kapsayıcılara dağıtırken yaklaşım yine "anahtar imajda olmasın" şeklindedir; orkestrasyon aracı başlatma sırasında enjekte eder. Aşağıda compose için en minimal yazım yer almaktadır:

复制# docker-compose.yml 片段
services:
  app:
    image: your-app:latest
    environment:
      API_BASE: https://api.llmzhongzhuan.com/v1
      API_KEY: ${API_KEY}   # 从宿主机环境或 .env 读取，不写进镜像

Kubernetes'te bu bir Secret referansına dönüşür; temel ilke değişmez. Ayrıca farklı ortamlar için farklı hesaplar veya API anahtarları hazırlamanız önerilir (örneğin geliştirme, ön üretim ve üretim için ayrı setler). Böylece bir ortamın anahtarı sızdırılırsa veya bakiyesi biterse, canlı ortam etkilenmez. Her hesabın yalnızca bir anahtarı olduğu için, çoklu ortam için birden fazla hesap kullanmalı ve her biri için uygun miktarda bakiye yüklemelisiniz.

Son olarak günlükler. Çoğu çerçeve hata ayıklama modunda tam istek başlıklarını yazdırır; bunlar Authorization içerir. Üretim ortamında bu hata ayıklama çıktısını kapatın veya günlük filtrelerinde anahtarı gizleyin. usage alanını kaydetmek iyi bir alışkanlıktır; faturalarla karşılaştırmanızı ve bir işlevin isteminin aniden uzadığını erken fark etmenizi sağlar.

Hata durumunda hata ayıklama sırası

Entegrasyon aşamasındaki sorunların %90'ı birkaç noktada toplanır; en hızlı çözüm için aşağıdaki sırayı izleyin:

1. 401: Anahtar boş, kopyalarken boşluk içeriyor veya sıfırlamadan sonra eski anahtarı kullanmaya devam ediyorsunuz.
2. 404: Adres, /v1 kök yolunu içermediği şekilde yazılmış veya /chat/completions birden fazla kez eklenmiş.
3. 402: Hata kodu no_credit ise, bakiye doldurulması gerekir çünkü ön ödemeli kredi bitti veya ücretsiz deneme kredisi süresi doldu.
4. 400: Yaygın nedenler, girdi ile max_tokens toplamının 100.000'i aşması veya istek gövdesinin 8 MB'ı aşmasıdır.
5. 429 / 503: İlki dakika başına 300 istek hız limitidir, ikincisi upstream_busy'dir. Birkaç saniye bekleyip yeniden deneyin; detaylar için stabilite pratikleri bölümüne bakın.

Göz ardı edilmesi kolay bir başka sorun da ağ ortamıdır. Kurumsal iç ağlar, proxy yazılımları veya güvenlik duvarı kuralları, alan adı çözümlemesinin başarılı olmasına rağmen HTTPS bağlantısının kurulmasını engelleyebilir; bu durum belirgin bir hata kodundan ziyade uzun süre takılıp kalan ve sonunda zaman aşımına uğrayan istekler olarak görünür. Bu durumda, önce aynı makinede /v1/models uç noktasına curl ile erişmeyi deneyin. Bağlantı başarılı olursa sorun uygulama katmanındadır; başarısız olursa proxy ve güvenlik duvarı ayarlarınızı kontrol edin. Sorun giderme sürecini ekip dokümanlarınıza kaydedin, böylece yeni çalışanlar sonraki entegrasyonlarda daha az sorun yaşar.

Üç değerin de doğru olmasına rağmen hâlâ başarısız olursanız, çerçevenin kendi sorunlarını elemek için önce doğrudan curl ile bir istek gönderin. Proxy'nin tam olarak ne yaptığını öğrenmek isterseniz, Proxy mekanikleri bölümüne geri dönebilirsiniz.