HI ▾
API कुंजी पाएँ

Python में Character AI API: OpenAI SDK सेटअप

एक character ai api python वर्कफ़्लो का उपयोग करने के लिए, आधिकारिक openai पैकेज इंस्टॉल करें, इसके बेस URL को एक OpenAI-कम्पैटिबल एंडपॉइंट पर पॉइंट करें और मॉडल को uncensored पर सेट करें। इस पेज का शेष भाग उस पर इतिहास, स्ट्रीमिंग, रेट्राइज़ और लागत ट्रैकिंग के साथ एक छोटा पर्सोना चैट बनाता है।

एक प्लेटफ़ॉर्म पर टर्मिनल, लिंक्ड क्यूब्स में स्ट्रीमिंग चैट बबल्स को दर्शाता है, जो एक Python चैट क्लाइंट का प्रतिनिधित्व करता है

मुख्य बिंदु

  1. मानक SDK में दो मान बदलते हैं: base_url और api_key।
  2. पात्र का व्यवहार सिस्टम संदेश और उस इतिहास से आता है जिसे आप प्रत्येक बारी में फिर से भेजते हैं।
  3. स्ट्रीमिंग, टूल कॉलिंग और JSON मोड सभी एक ही क्लाइंट के माध्यम से काम करते हैं।
  4. HTTP 429 को एक छोटे वेट के साथ संभालें और एक पूर्ण कुंजी पर समानांतर कॉल को 8 पर सीमित करें।

इंस्टॉल करें और कनेक्ट करें

कोई विशेष क्लाइंट लाइब्रेरी नहीं है। Python में Character apps बाकी सब कुछ के साथ openai पैकेज का ही उपयोग करते हैं। इसे इंस्टॉल करें और अपनी कुंजी एक एनवायरनमेंट वेरिएबल में रखें।

pip install openai
export API_KEY="paste-your-key-here"

सबसे पहले API कुंजी पृष्ठ से एक कुंजी प्राप्त करें। नए खातों के पास एक ही क्लिक से $0.50 का मुफ़्त ट्रायल क्रेडिट दावा करने का विकल्प होता है, बिना कार्ड के। फिर क्लाइंट बनाएँ:

import os
from openai import OpenAI

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

resp = client.chat.completions.create(
    model="uncensored",
    messages=[{"role": "user", "content": "Say hello in one sentence."}],
)
print(resp.choices[0].message.content)
print(resp.usage)

यदि वह एक ग्रीटिंग और एक उपयोग ऑब्जेक्ट प्रिंट करता है, तो कनेक्शन ठीक है। सेवा POST /v1/chat/completions और GET /v1/models एक्सपोज़ करती है। टेक्स्ट चैट के अलावा कुछ भी, जैसे इमेजेस, एम्बेडिंग्स या फाइन-ट्यूनिंग, उपलब्ध नहीं है।

मेमोरी के साथ एक कैरेक्टर चैट लूप

API स्टेटलेस है। यह पिछली बारी को याद नहीं रखता, इसलिए आपके प्रोग्राम को हर बार पूरी बातचीत भेजनी होगी। एक पर्सोना के लिए इसका मतलब है एक सिस्टम संदेश के बाद बारी-बारी से यूजर और असिस्टेंट संदेश। यह लूप उन्हें एक सूची में रखता है।

import os
from openai import OpenAI

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

PERSONA = (
    "You are Mara, a dry-witted ship engineer in a space opera. "
    "Stay in character, answer in two to four sentences, and never mention being an AI."
)
history = [{"role": "system", "content": PERSONA}]

while True:
    user = input("you> ").strip()
    if user in {"quit", "exit"}:
        break
    history.append({"role": "user", "content": user})
    resp = client.chat.completions.create(
        model="uncensored",
        messages=history,
        temperature=0.9,
        top_p=0.95,
    )
    text = resp.choices[0].message.content
    history.append({"role": "assistant", "content": text})
    print("mara>", text)

सैम्पलिंग सेटिंग्स मॉडल को पास की जाती हैं: temperature, top_p, stop, seed और फ्रीक्वेंसी व प्रेजेंस पेनल्टी। रोलप्ले के लिए, 0.8 और 1.0 के बीच एक तापमान आमतौर पर अधिक जीवंत संवाद देता है, जबकि एक कम मान संरचित कार्यों के लिए उपयुक्त है। समान स्थितियों में दो प्रॉम्प्ट संस्करणों की तुलना करने के लिए seed सेट करें।

बातचीत को सेव और रीलोड करें

एक चैट जो स्क्रिप्ट के समाप्त होने पर गायब हो जाती है, वह एक डेमो है, ऐप नहीं। इतिहास को एक JSON फ़ाइल के रूप में स्टोर करना वह सबसे छोटा कदम है जो इसे स्थायी महसूस कराता है। नीचे दिया गया हेल्पर यदि वे मौजूद हैं तो एक कैरेक्टर के सेव्ड संदेशों को लोड करता है और हर बारी के बाद उन्हें वापस लिखता है।

import json
from pathlib import Path

def load(name, persona):
    path = Path(f"{name}.json")
    if path.exists():
        return json.loads(path.read_text())
    return [{"role": "system", "content": persona}]

def save(name, history):
    Path(f"{name}.json").write_text(json.dumps(history, indent=2))

स्टार्टअप पर load कॉल करें और असिस्टेंट रिप्लाई जोड़ने के बाद save करें। प्रत्येक कैरेक्टर और प्रत्येक यूजर के लिए एक फ़ाइल रखें, और आपके पास मल्टी-कैरेक्टर सेटअप पहले से मौजूद है। एक बार जब आप फ़ाइलों से आगे निकल जाएं, तो डिक्ट्स की उसी सूची को बिना किसी बदलाव के डेटाबेस कॉलम या की-वैल्यू स्टोर में फिट किया जा सकता है, क्योंकि यह API द्वारा अपेक्षित ही है।

विचार करें कि आप क्या स्टोर करते हैं। इतिहास में वे व्यक्तिगत विवरण हो सकते हैं जो यूजर ने टाइप किए हैं। इस API को भेजे गए प्रॉम्प्ट प्रशिक्षण के लिए उपयोग नहीं किए जाते हैं, लेकिन आपकी अपनी फ़ाइलें और लॉग आपकी ज़िम्मेदारी हैं, इसलिए तय करें कि आप उन्हें कितने समय तक रखते हैं और उन्हें कौन पढ़ सकता है।

इसे महंगा होने से पहले इतिहास को ट्रिम करें

कॉन्टेक्स्ट विंडो 100,000 टोकन की है, प्रॉम्प्ट और कंप्लीशन सहित। एक लंबा रोलप्ले समय के साथ उस तक पहुंच सकता है, और लागत बढ़ती जाती है क्योंकि आप हर टर्न पर पूरी हिस्ट्री के लिए इनपुट टोकन के लिए भुगतान करते हैं। एक सरल दृष्टिकोण सिस्टम मैसेज और पिछले N एक्सचेंजेस को बनाए रखता है।

def trimmed(history, keep=20):
    system = history[:1]
    rest = history[1:]
    return system + rest[-keep:]

# inside the loop
resp = client.chat.completions.create(
    model="uncensored",
    messages=trimmed(history),
)

लंबी कहानियों के लिए एक बेहतर डिज़ाइन एक रोलिंग सारांश है। हर 30 संदेशों पर, मॉडल से पुराने हिस्से का 200 शब्दों में सारांश बनवाने को कहें, उन संदेशों को सिस्टम संदेश के अंदर सारांश के साथ बदल दें, और जारी रखें। आप कुछ विवरण खो देते हैं लेकिन प्लॉट थ्रेड्स बनाए रखते हैं, और प्रति-बारी लागत समान रहती है।

यहाँ 8,000 टोकन के इतिहास और 300 टोकन की रिप्लाई वाली एक चैट के लिए गणना है: इनपुट है 8,000 x $0.15 / 1,000,000 = $0.0012, आउटपुट है 300 x $0.50 / 1,000,000 = $0.00015, इसलिए प्रति बारी $0.00135। उस इतिहास को 2,000 टोकन तक ट्रिम करने से बारी $0.0003 + $0.00015 = $0.00045 हो जाती है। यह अधिकांश बातचीत के लिए कीमत का एक तिहाई है।

जवाबों को लिखते समय स्ट्रीम करें

एक चैट इंटरफ़ेस के लिए आप चाहते हैं कि टेक्स्ट जनरेट होते हुए दिखाई दे। stream=True सेट करें और चंक पर इटरेट करें। स्ट्रीमिंग सर्वर-सेंट इवेंट्स के माध्यम से चलती है, और आप आखिरी चंक में उपयोग का अनुरोध कर सकते हैं।

stream = client.chat.completions.create(
    model="uncensored",
    messages=history,
    stream=True,
    stream_options={"include_usage": True},
)

parts = []
for chunk in stream:
    if chunk.choices and chunk.choices[0].delta.content:
        piece = chunk.choices[0].delta.content
        parts.append(piece)
        print(piece, end="", flush=True)
print()
reply = "".join(parts)

याद रखें कि एक स्ट्रीमिंग अनुरोध स्ट्रीम समाप्त होने तक अपनी कॉन्करेंसी स्लॉट को हॉल्ड करता है। एक फुल कुंजी पर आप एक साथ 8 चला सकते हैं; एक ट्रायल कुंजी पर केवल 2। यदि कोई यूजर टैब बंद कर देता है, तो सुनिश्चित करें कि आपका सर्वर अपस्ट्रीम स्ट्रीम को भी बंद कर दे, वरना वह स्लॉट को व्यस्त रखता है।

asyncio के साथ एक साथ कई चैट चलाएं

एक वेब सर्विस जो एक ही समय में कई यूजर्स को हैंडल करती है, उसे async क्लाइंट की आवश्यकता होती है। पैटर्न सरल है: एक शेयर्ड AsyncOpenAI क्लाइंट, एक सेमाफोर जो आपकी कॉन्करेंसी लिमिट के आकार का है, और प्रत्येक बातचीत के लिए एक कोरूटीन।

import asyncio
import os
from openai import AsyncOpenAI

client = AsyncOpenAI(base_url="https://api.characteraiapi.com/v1", api_key=os.environ["API_KEY"])
gate = asyncio.Semaphore(8)  # use 2 on a trial key

async def reply(messages):
    async with gate:
        r = await client.chat.completions.create(model="uncensored", messages=messages)
        return r.choices[0].message.content

async def main():
    jobs = [
        reply([{"role": "user", "content": f"Give character {i} a one-line greeting."}])
        for i in range(20)
    ]
    for text in await asyncio.gather(*jobs):
        print(text)

asyncio.run(main())

बीस जॉब्स बनाई जाती हैं, लेकिन केवल आठ एक साथ चलते हैं। शेष सेमाफोर के अंदर अपनी बारी का इंतज़ार करते हैं, ताकि आप concurrency एरर ट्रिगर न करें। यदि आपकी सर्विस स्ट्रीमिंग रिप्लाइज़ को हैंडल करती है, तो याद रखें कि प्रत्येक ओपन स्ट्रीम समाप्त होने तक गिनती में आता है, जिसका अर्थ है कि क्लाइंट साइड पर स्लो रीडर्स आपकी उम्मीद से अधिक देर तक स्लॉट पकड़े रख सकते हैं। क्लाइंट पर टाइमआउट सेट करें और उन स्ट्रीम्स को कैंसल करें जिनके यूज़र्स चले गए हैं।

प्रति-मिनट की लिमिट अलग है। एक फुल कुंजी पर प्रति मिनट 300 अनुरोधों पर, 20 छोटे कॉल्स का एक बर्स्ट ठीक है, लेकिन एक लूप जो हजारों कॉल्स भेजता है, उसे पेसिंग की आवश्यकता होती है। एक सरल दृष्टिकोण टास्क लॉन्च के बीच एक सेकंड के अंश के लिए सोना है, या एक टोकन बकेट लाइब्रेरी का उपयोग करना है जो आपके स्टैक में फिट बैठती है।

टूल्स और JSON मोड

कैरेक्टर बॉट्स को अक्सर स्ट्रक्चर्ड आउटपुट की आवश्यकता होती है: एक मूड स्कोर, एक इन्वेंटरी अपडेट, प्लेयर के लिए विकल्पों की एक सूची। JSON मोड रिप्लाइज़ को वैध JSON बनाता है, और आप प्रॉम्प्ट में आकार का वर्णन करते हैं।

import json

resp = client.chat.completions.create(
    model="uncensored",
    response_format={"type": "json_object"},
    messages=[
        {"role": "system", "content": "Reply with JSON only: {\"mood\": string, \"choices\": [string, string, string]}"},
        {"role": "user", "content": "Mara finds a sealed hatch in the cargo bay."},
    ],
)
data = json.loads(resp.choices[0].message.content)
print(data["mood"], data["choices"])

टूल कॉलिंग मानक tools और tool_choice फ़ील्ड्स का उपयोग करती है। मॉडल एक tool_calls एंट्री लौटाता है, आपका कोड फ़ंक्शन चलाता है, और आप role: "tool" के साथ एक मैसेज के रूप में रिजल्ट वापस भेजते हैं।

tools = [{
    "type": "function",
    "function": {
        "name": "roll_dice",
        "description": "Roll an n-sided die",
        "parameters": {
            "type": "object",
            "properties": {"sides": {"type": "integer"}},
            "required": ["sides"],
        },
    },
}]

msgs = [{"role": "user", "content": "Mara tries to force the hatch. Roll a d20."}]
first = client.chat.completions.create(model="uncensored", messages=msgs, tools=tools)
call = first.choices[0].message.tool_calls[0]

msgs.append(first.choices[0].message)
msgs.append({"role": "tool", "tool_call_id": call.id, "content": "17"})
final = client.chat.completions.create(model="uncensored", messages=msgs, tools=tools)
print(final.choices[0].message.content)

इस पर भरोसा करने से पहले इसे अपने प्रॉम्प्ट्स पर टेस्ट करें। ओपन-वेट मॉडल्स टूल कॉल कितनी भरोसेमंदी से उत्पन्न करते हैं, इसमें अलग हैं, इसलिए जब tool_calls खाली हो तो एक फॉलबैक पाथ रखें।

एरर्स और रेट लिमिट्स हैंडल करें

एक फुल कुंजी 8 कॉन्करेंट अनुरोधों और प्रति मिनट 300 अनुरोधों की अनुमति देता है। एक ट्रायल कुंजी 2 और 60 की अनुमति देता है। लिमिट से अधिक होने पर आपको HTTP 429 मिलता है जिसमें एरर कोड rate_limited (प्रति मिनट बहुत अधिक) या concurrency (एक साथ बहुत अधिक) होता है। एक अस्थायी ओवरलोड भी 429 लौटाता है, Retry-After: 5 हेडर के साथ। SDK इनके लिए RateLimitError उठाता है, और आप कॉल को रीट्राई में लपेट सकते हैं।

import time
import openai

def chat(messages, tries=4):
    for attempt in range(tries):
        try:
            return client.chat.completions.create(model="uncensored", messages=messages)
        except openai.RateLimitError as err:
            wait = 5
            retry_after = err.response.headers.get("Retry-After")
            if retry_after:
                wait = int(retry_after)
            time.sleep(wait * (attempt + 1))
    raise RuntimeError("still rate limited")

यदि आप एक ही प्रक्रिया से कई संवाद चलाते हैं, तो उन्हें एक सीमांकक (semaphore) से बांधें ताकि एक साथ 8 अनुरोधों से अधिक न हों। asyncio और AsyncOpenAI के साथ, प्रत्येक कॉल के चारों ओर asyncio.Semaphore(8) पर्याप्त है। प्रतिक्रिया हेडर X-RateLimit-Limit-Requests और X-RateLimit-Limit-Concurrency आपकी कुंजी के लिए लागू सीमाओं की पुष्टि करते हैं, और X-Balance-USD आपका शेष क्रेडिट दिखाता है।

फेल या रिफ्यूज किए गए अनुरोधों के लिए चार्ज नहीं किया जाता है, इसलिए एरर पर रेट्राइज़ से आपको कोई लागत नहीं आती। जब आपका बैलेंस कम हो जाता है, तो $20 से $500 तक टॉप-अप करें; $50 या उससे अधिक की राशि पर $50, $100 और $200 के स्तर पर क्रमशः 5%, 10% या 15% का बोनस मिलता है। विवरण मूल्य निर्धारण पृष्ठ पर हैं, और पूर्ण पैरामीटर सूची दस्तावेज़ में है।

ट्रैक करें कि प्रत्येक सेशन की लागत कितनी है

प्रत्येक गैर-स्ट्रीमिंग प्रतिक्रिया में usage ऑब्जेक्ट होता है जिसमें prompt_tokens और completion_tokens होते हैं। जब आप स्ट्रीम करते हैं और उपयोग का अनुरोध करते हैं, तो अंतिम चंक इसे वहन करता है। उन संख्याओं को एक छोटे फ़ंक्शन के माध्यम से डॉलर में बदलें और सत्र ID के बगल में लॉग करें।

IN_PRICE = 0.15 / 1_000_000
OUT_PRICE = 0.50 / 1_000_000

def cost(usage):
    return usage.prompt_tokens * IN_PRICE + usage.completion_tokens * OUT_PRICE

resp = client.chat.completions.create(
    model="uncensored",
    messages=[{"role": "user", "content": "Describe the engine room in three lines."}],
)
print(f"${cost(resp.usage):.6f}")

इन नंबरों के साथ आप व्यावहारिक सवालों का जवाब दे सकते हैं। यदि एक औसत सेशन 40 टर्न्स का है, जिसमें हिस्ट्री 500 से 6,000 इनपुट टोकन और प्रति रिप्लाई 250 आउटपुट टोकन तक बढ़ती है, तो औसत इनपुट लगभग 3,250 टोकन है। प्रति टर्न इनपुट लागत लगभग 3,250 x $0.15 / 1,000,000 = $0.00049 है और आउटपुट 250 x $0.50 / 1,000,000 = $0.000125 है, इसलिए प्रति टर्न लगभग $0.00061 और 40 टर्न्स के लिए $0.0245। एक यूज़र जो महीने में 20 सेशन खेलता है, आपको लगभग 49 सेंट्स का खर्च लाता है। यह एक नंबर है जिसके आसपास आप एक प्रोडक्ट प्राइस कर सकते हैं।

कनेक्शन जाँच को एक वर्चुअल एनवायरनमेंट के भीतर चलाएं ताकि पैकेज संस्करण प्रोजेक्ट के लिए स्थिर रहे, और स्टार्टअप पर client.models.list() के साथ मॉडल की सूची एक बार बनाएं। यदि वह कॉल विफल हो जाती है, तो आपको किसी उपयोगकर्ता से पहले ही गलत कुंजी या गलत बेस URL के बारे में पता चल जाता है, और आप चैट लूप की गहराई में स्टैक ट्रेस के बजाय एक स्पष्ट संदेश प्रिंट कर सकते हैं। जो टीमें इस कोड को डिप्लॉय करती हैं, वे अक्सर हेल्थ चेक राउट पर उसी कॉल को जोड़ती हैं।

प्रति सेशन लागत लॉग करें और टॉप पांच प्रतिशत देखें। लंबे सेशन जो कभी हिस्ट्री ट्रिम नहीं करते, वे आमतौर पर बिल का बड़ा हिस्सा होते हैं, और फिक्स वही ट्रिमिंग या सारांश दृष्टिकोण है जो पहले वर्णित है।

प्रश्न और उत्तर

क्या Character.ai की कोई आधिकारिक Python लाइब्रेरी है?

यह सर्विस Character.ai नहीं है और इसकी कोई अलग लाइब्रेरी नहीं है। आप ऊपर दिए गए बेस URL और मॉडल ID के साथ मानक openai पैकेज का उपयोग करते हैं।

मैसेजेस के बीच कैरेक्टर को कंसीस्टेंट कैसे रखें?

पर्सोना को सिस्टम मैसेज में डालें और प्रत्येक अनुरोध के साथ हालिया हिस्ट्री फिर से भेजें। API आपके लिए कन्वर्सेशन्स स्टोर नहीं करता है।

क्या मैं async क्लाइंट का उपयोग कर सकता हूँ?

हाँ। AsyncOpenAI समान base_url और api_key स्वीकार करता है। पूर्ण कुंजी पर समानांतर कॉल को 8 तक और ट्रायल कुंजी पर 2 तक सीमित करें।

एक चैट टर्न का खर्च कितना है?

1,500 इनपुट टोकन और 300 आउटपुट टोकन के साथ यह $0.000375 है, जो 1M टोकन के लिए $0.15 और $0.50 के आधार पर है। लंबा इतिहास इनपुट का हिस्सा बढ़ा देता है।

क्या Python SDK के साथ स्ट्रीमिंग काम करता है?

हाँ। stream=True पास करें और चंक पर इटरेट करें। उपयोग स्ट्रीम के अंत में भेजा जाता है।

आपकी कुंजी बस एक फ़ॉर्म दूर है

एक खाता बनाएँ, कुंजी कॉपी करें, बेस URL बदलें। सेटअप यही है।

API कुंजी पाएँ