Temel noktalar
- ChatOpenAI değişmeden çalışır: base_url, api_key ve model değerlerini
uncensoredolarak ayarlayın. - API, fonksiyon çağırma (tool calling) desteği sunar; bu nedenle bind_tools ve önceden hazırlanmış ajan ikisi de çalışır.
- Döngü yinelemelerini sınırlayın ve araç argümanlarını doğrulayın; açık ağırlıklı modeller bazen bunları yanlış yapabilir.
- Ajanları eşzamanlı çalıştırırken tam anahtarınızda 8 eşzamanlı istek sınırına dikkat edin.
Başlamadan önce ihtiyacınız olanlar
Python 3.10 veya üzeri sürüm, bir API anahtarı ve birkaç paket gerekir. Anahtarı API anahtarı sayfası üzerinden alırsınız: Google veya e-posta/şifre ile giriş yapın ve tek tıkla $0,50 deneme kredisi talep edin. Deneme anahtarı dakikada 60 istek ve 2 eşzamanlı istek izni verir; bu, makaledeki her şey için, bir seferde bir ajan çalıştırdığınız sürece yeterlidir.
pip install langchain-openai langchain-core langgraph
export API_KEY="paste-your-key-here"API, POST /v1/chat/completions ve GET /v1/models uç noktalarını açığa çıkarır. LangChain'e yalnızca ilki gerekir. Model, yetişkinlerin yasal kullanımı için içerik reddi olmadan yanıtlamak üzere ayarlanmış tek bir açık ağırlıklı modeldir; bağımsız bir sağlayıcı tarafından çalıştırılır ve herhangi bir model satıcısının resmi API'si değildir. Editörünüzün yanında bulundurmak isterseniz dokümantasyon başlıkları ve limitleri listeler.
Parçaların API'ye nasıl eşlendiği
LangChain'in ağ üzerinde ne yaptığını bilmek faydalıdır. Bir HumanMessage, role user olan bir mesaja dönüşür. Bir AIMessage assistant olur ve araç çağrıları içerdiğinde, bunlar assistant mesajında bir tool_calls dizisi olarak görünür. Bir ToolMessage, eşleşen çağrı kimliğiyle role tool olur. Sistem istemi, role system ile ilk olarak gönderilir.
Bu eşleme hata ayıklama için önemlidir. Bir ajan garip davranırsa, her çağrıdan önce mesaj listesini yazdırın ve bir transkript gibi okuyun. Sorunu genellikle bir dakika içinde bulursunuz: boş bir araç sonucu, eşleşmeyen bir çağrı kimliği veya beklediğinizden çok daha uzun hale gelen bir geçmiş. Agentic kelimesi bunu sihirli gibi gösterse de, her adım sıradan bir sohbet tamamlama isteğidir.
Adım 1: ChatOpenAI'yi Bağlayın
Tüm entegrasyon üç argümandan oluşur. LangChain standart OpenAI tarzı istekler oluşturur, bu nedenle sunucu fark edemez.
import os
from langchain_openai import ChatOpenAI
llm = ChatOpenAI(
model="uncensored",
base_url="https://api.uncensoredvideo.cc/v1",
api_key=os.environ["API_KEY"],
temperature=0.7,
max_retries=2,
)
print(llm.invoke("Name three beats of a heist scene, one line each.").content)Bu üç satır yazdırılırsa, altyapı çalışıyor demektir. 401 alırsanız anahtarı kontrol edin. 404 alırsanız URL'nin /v1 ile bittiğinden ve ekstra yol içermediğinden emin olun. max_retries bir istemci seçeneğidir ve Retry-After: 5 taşıyan geçici 429 yanıtlarında yardımcı olur.
Akış, herhangi bir OpenAI modeliyle kullandığınız gibi çalışır: llm.stream(...) çağrısı yapın ve yineleyin. Son parça kullanım bilgisini taşır, böylece her çağrı için token sayılarını kaydedebilirsiniz.
Adım 2: Araçları Tanımlayın
Bir ajan bir döngüdür: model konuşmayı okur, ya yanıtlar ya da bir araç ister, kodunuz aracı çalıştırır ve sonuç modele geri döner. Aşağıdaki araçlar sıradan Python fonksiyonlarıdır. Kasıtlı olarak sıkıcılar, çünkü amaç mekanikleri görmektir.
from langchain_core.tools import tool
@tool
def word_count(text: str) -> int:
"""Count the words in a piece of text."""
return len(text.split())
@tool
def spoken_minutes(words: int, words_per_minute: int = 150) -> float:
"""Estimate how many minutes a script takes to read aloud."""
return round(words / words_per_minute, 2)
tools = [word_count, spoken_minutes]Docstring ve tip ipuçları, modelin gördüğü araç açıklaması ve şeması haline gelir. Bunları bir meslektaşınıza açıklıyormuşsunuz gibi yazın. Belirsiz bir docstring, bir ajanın yanlış aracı seçmesinin en yaygın nedenidir. Video için betikler yazıyorsanız, aynı desen; Sora 2 betik oluşturucu sayfasında ele alınan, çekim listelerini arayan veya uzunluk bütçesi kontrol eden araçlara ölçeklenir.
Adım 3: Ajan döngüsünü elle çalıştırın
Önceden hazırlanmış yardımcılar döngüyü gizler. Bunu kendiniz bir kez yazmak, sonraki her hatayı bulmayı kolaylaştırır.
from langchain_core.messages import HumanMessage, ToolMessage
by_name = {t.name: t for t in tools}
llm_tools = llm.bind_tools(tools)
messages = [HumanMessage(
"Here is a draft: 'The vault door hums. Nina counts to three, "
"then cuts the power.' How many words is it, and how long is it read aloud?"
)]
for step in range(6):
ai = llm_tools.invoke(messages)
messages.append(ai)
if not ai.tool_calls:
break
for call in ai.tool_calls:
result = by_name[call["name"]].invoke(call["args"])
messages.append(ToolMessage(content=str(result), tool_call_id=call["id"]))
print(messages[-1].content)Üç detay önemlidir. range(6) sınırı, kafası karışmış bir modelin sonsuza kadar döngüye girmesini engeller ve harcamanızı da sınırlar. tool_call_id, yanıt verdiği çağrıyla eşleşmelidir. Ve model bir yanıtta birden fazla araç isteyebilir; bu nedenle iç döngü bir listeyi işler.
Arka planda, istek bir tools dizisi taşır ve yanıt tool_calls içerir; sonuçlar role: "tool" ile mesajlar olarak döndürülür. tool_choice ile belirli bir aracı zorlayabilirsiniz; bu, LangChain'de bind_tools'e bir argüman olarak sunulur.
Adım 4: Önceden hazırlanmış LangGraph ajanını kullanın
Manuel döngü mantıklı hale geldiğinde, önceden hazırlanmış ajan satır sayısını azaltır. Aynı modeli ve aynı araçları alır.
import os
from langchain_openai import ChatOpenAI
from langgraph.prebuilt import create_react_agent
llm = ChatOpenAI(
model="uncensored",
base_url="https://api.uncensoredvideo.cc/v1",
api_key=os.environ["API_KEY"],
)
agent = create_react_agent(llm, tools)
out = agent.invoke({"messages": [("user", "How long is a 450 word script read aloud?")]})
print(out["messages"][-1].content)LangChain ve LangGraph, sürümler arasında API'lerini değiştirir ve bazı yardımcı işlevler yeniden adlandırılmış veya taşınmıştır. Bir import başarısız olursa, eşdeğer ajan oluşturucu için mevcut LangChain belgelerine bakın. Bağlantı kısmı, base URL ile ChatOpenAI aynı kalır.
Döngü ile grafik arasında seçim yapmak
El ile yazılmış döngü, birkaç araç arasından seçim yapan ve duran ajanlar için yeterlidir. Okuması kolaydır, günlüğe kaydetmesi kolaydır ve framework sürprizleri yoktur. Duruma bağlı dallar gerektiğinde LangGraph'a geçin: işi tekrar işlemek için geri gönderen bir gözden geçirme adımı, riskli bir araç çalışmadan önce insan onayı veya sonuçları birbirine aktaran birkaç uzman alt ajan.
Ne seçerseniz seçin, her düğümü küçük tutun ve ona tek bir iş verin. Kısa bir numaralı JSON listesi çıkaran bir planlama düğümü, araçları çalıştıran bir yürütme düğümü ve nihai metni üreten bir yazma düğümü, tek bir devasa istemden daha kolay test edilir. Ayrıca farklı sıcaklıklar kullanmanızı da sağlar: planlama ve araç kullanımı için düşük, yazma adımı için daha yüksek. Her düğüm normal bir sohbet tamamlama çağrısı olduğu için, aynı anahtar, URL ve model adı hepsini karşılar ve maliyet, çağrıların toplamıdır.
Bir alışkanlık daha: Çalışan token toplamını yazdırın. Demo'da ucuz görünen ajanlar, dağınık gerçek görevlerde on kat daha fazla harcayabilir ve her yanıtta yer alan kullanım verileri, bunu bakiyenizde bir sürprize dönüşmeden ilk çalıştırmada görünür kılar.
Bellek, test ve yapılandırılmış çıktı
Yukarıdaki döngü, betik sonlandığında her şeyi unutur. En basit hafıza mesaj listesinin kendisidir: kullanıcı turları arasında tutun, her yeni soruyu ekleyin ve uzun olduğunda en eski mesajları kısaltın. Uzun oturumlar için, eski mesajları model tarafından yazılan kısa bir özetle değiştirin. Girdi token başına faturalandırıldığı için, 500 token'lık bir özet hem maliyet hem de odak açısından 20.000 token ham geçmişten daha iyidir.
Ajanları test etmek çoğunlukla gözlemlenebilir davranışları kontrol etmektir. Sıcaklığı 0'a ayarlayın veya API'nin geçirdiği sabit bir seed geçirin, böylece çalıştırmalar daha tekrarlanabilir olur. Ardından, hangi aracın çağrılması gerektiğini bildiğiniz birkaç soru yazın ve cevabın tam kelimesine değil, mesaj listesindeki araç adlarına ve argümanlarına göre assert yapın. Bunları bir istem veya araç açıklamasındaki her değişiklikten sonra çalıştırın. Bir docstring'i değiştirmek modelin seçtiği aracı değiştirebilir ve bir test bunu fark etmenin en ucuz yoludur.
Her çalıştırma için üç şeyi günlüğe kaydedin: adım sayısı, argümanlarıyla birlikte araç çağrıları ve token kullanımı. Bir çalıştırma başarısız olduğunda, bu üç satır size modelin kötü mü seçtiğini, bir aracın mı başarısız olduğunu yoksa döngünün adımları mı tükettiğini söyler.
Yapılandırılmış çıktı ve JSON modu
Ajanlar genellikle metin değil, veri döndürmek zorundadır. API, response_format: {"type":"json_object"} aracılığıyla JSON modunu destekler. LangChain'de bunu llm.bind(response_format={"type": "json_object"}) ile isteyebilirsiniz. İstemde modele cevabın bir JSON nesnesi olması gerektiğini ve beklediğiniz anahtarları adlandırın, ardından dizgeyi ayrıştırın ve Pydantic ile doğrulayın. Ayrıştırma adımının her zaman başarılı olacağına güvenmeyin; hatayı modele bir kez geri gönderen bir yeniden deneme ile sarın.
Tuzaklar ve nasıl düzeltilecekleri
- Kötü araç argümanları. Açık ağırlıklı bir model, bir tam sayı tanımladığınız yerde bir dizge gönderir. Argümanları doğrulayın, araçtan kısa bir hata mesajı döndürün ve modelin bir sonraki adımda kendini düzeltmesine izin verin.
- Kontrolsüz döngüler. Her zaman yinelemeleri sınırlayın. Geliştirme sırasında her adımı günlüğe kaydedin.
- Paralel ajanlar. Tam anahtar 8 eşzamanlı istek izni verir. Bir toplu işlem çalıştırıyorsanız,
llm.batchüzerindeconfig={"max_concurrency": 4}ayarlayarak pay bırakın. Limiti aşmakconcurrencykoduyla 429 döndürür; dakikada 300 istek limitini aşmakrate_limiteddöndürür. - Akış ve araçlar. Akışlı bir istek, akış bitene kadar eşzamanlılık slotunu tutar; bu nedenle deneme anahtarında bir akış işleyicisi içinde yeni çağrılar başlatmayın.
- Büyüyen geçmiş. Her adım tam mesaj listesini yeniden gönderir. Bağlam penceresi 100.000 token'dır, ancak her çağrıda girdi için ödeme yaparsınız.
Bir ajan çalıştırmanın maliyeti
Bir görevi tamamlamak için 4 model çağrısı yapan mütevazı bir ajan alın; ortalama istem 3.000 token ve çağrı başına 200 çıktı token'ı. Girdi: 4 x 3.000 = 12.000 token, bu da 12.000 x $0,15 / 1.000.000 = $0,0018 eder. Çıktı: 4 x 200 = 800 token, bu da $0,0004 eder. Bir çalıştırma $0,0022 maliyetinde olur, bu nedenle 1.000 çalıştırma $2,20 eder. $0,50 deneme kredisi yaklaşık 227 böyle çalıştırmayı kapsar. Başarısız veya reddedilen istekler için ücret alınmaz ve kredi asla sona ermez. Yükleme miktarları ve bonuslar için fiyatlandırma sayfasına bakın. Bu site yalnızca kripto kabul eder, TRC20 üzerinde USDT veya Base üzerinde USDC.
