AR ▾
احصل على مفتاح API

واجهة برمجة تطبيقات Character AI في Python: إعداد SDK الخاص بـ OpenAI

لاستخدام سير عمل Python مع واجهة برمجة تطبيقات للذكاء الاصطناعي للشخصيات، ثبّت الحزمة الرسمية لـ OpenAI، وجّه عنوان URL الأساسي الخاص بها إلى نقطة نهاية متوافقة مع OpenAI، واضبط النموذج على uncensored. تبني بقية هذه الصفحة محادثة شخصية صغيرة فوق ذلك، مع السجل، والبث المتدفق، وإعادة المحاولة، وتتبع التكلفة.

طرفية على منصة تبث فقاعات الدردشة إلى مكعبات مرتبطة، لتمثيل عميل دردشة Python

نقاط رئيسية

  1. تتغير قيمتان في OpenAI SDK القياسي: base_url و api_key.
  2. يأتي سلوك الشخصية من رسالة النظام بالإضافة إلى سجل المحادثة الذي تعيد إرساله في كل دور.
  3. يعمل البث المتدفق، واستدعاء الدوال، ووضع JSON جميعها عبر العميل نفسه.
  4. عالج HTTP 429 بفترة انتظار قصيرة وحدّ المكالمات المتزامنة إلى 8 باستخدام المفتاح الكامل.

التثبيت والاتصال

لا توجد مكتبة عميل خاصة. تستخدم تطبيقات الشخصيات في Python حزمة 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 × $0.15 / 1,000,000 = $0.0012، والمخرجات هي 300 × $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

تحتاج خدمة الويب التي تتعامل مع العديد من المستخدمين في نفس الوقت إلى العميل غير المتزامن. النمط بسيط: عميل AsyncOpenAI مشترك واحد، وقفل عدّادي (semaphore) بحجم يساوي حدّ التوازي الخاص بك، ووظيفة خفيفة (coroutine) لكل محادثة.

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")

إذا قمت بتشغيل العديد من المحادثات من عملية واحدة، حددها بسعة حتى لا تتجاوز 8 طلبات قيد التنفيذ. مع asyncio و AsyncOpenAI، asyncio.Semaphore(8) حول كل استدعاء يكفي. رؤوس الاستجابة X-RateLimit-Limit-Requests و X-RateLimit-Limit-Concurrency تؤكد الحدود التي تنطبق على مفتاحك، و X-Balance-USD يظهر رصيدك المتبقي.

لا تُحتسب رسوم على الطلبات الفاشلة أو المرفوضة، لذا لا تكلفك إعادة المحاولة عند الأخطاء. عندما ينفد رصيدك، قم بشحن الرصيد من $20 إلى $500؛ تحمل المبالغ من $50 مكافأة بنسبة 5% أو 10% أو 15% عند مستويات $50 و $100 و $200. التفاصيل موجودة في صفحة التسعير، وقائمة المعاملات الكاملة في المستندات.

تتبع تكلفة كل جلسة

تتضمن كل استجابة غير متدفقة كائن usage مع prompt_tokens و completion_tokens. عندما تبث وتطلب الاستخدام، تحمله القطعة الأخيرة. حوّل هذه الأرقام إلى دولارات باستخدام دالة صغيرة وسجّلها بجانب معرف الجلسة.

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 × $0.15 / 1,000,000 = $0.00049 والمخرجات هي 250 × $0.50 / 1,000,000 = $0.000125، لذا حوالي $0.00061 لكل تبادل و $0.0245 لـ 40 تبادل. مستخدم يلعب 20 جلسة في الشهر يكلفك حوالي 49 سنتاً. هذا رقم يمكنك تسعير منتج حوله.

قم بتشغيل فحص الاتصال داخل بيئة افتراضية بحيث يبقى إصدار الحزمة ثابتاً للمشروع، واعرض قائمة النماذج مرة واحدة باستخدام client.models.list() عند بدء التشغيل. إذا فشل ذلك الاستدعاء، تتعلم عن مفتاح خاطئ أو base URL خاطئ قبل أي مستخدم، ويمكنك طباعة رسالة واضحة بدلاً من تتبع المكدس بعمق داخل حلقة الدردشة. تضيف الفرق التي تنشر هذا الرمز نفس الاستدعاء إلى مسار فحص الصحة.

سجّل التكلفة لكل جلسة وانظر إلى أعلى خمسة في المئة. الجلسات الطويلة التي لا تقص السجل عادةً ما تهيمن على الفاتورة، والحل هو التقليم أو نهج الملخص الموصوف سابقًا.

أسئلة وأجوبة

هل توجد مكتبة Python رسمية لـ Character.ai؟

هذه الخدمة ليست Character.ai ولا تحتوي على مكتبة منفصلة. تستخدم الحزمة القياسية openai مع URL الأساسي ومعرف النموذج المذكورين أعلاه.

كيف أحافظ على اتساق الشخصية عبر الرسائل؟

ضع الشخصية في رسالة النظام وأعد إرسال السجل الحديث مع كل طلب. لا تخزن API المحادثات نيابة عنك.

هل يمكنني استخدام العميل غير المتزامن؟

نعم. يقبل AsyncOpenAI نفس base_url و api_key. قيّد المكالمات المتوازية إلى 8 على المفتاح الكامل أو 2 على المفتاح التجريبي.

كم تكلفة دور الدردشة الواحد؟

بـ 1,500 رمز إدخال و 300 رمز إخراج، التكلفة هي $0.000375، استنادًا إلى $0.15 و $0.50 لكل 1M رمز. السجل الأطول يرفع حصة الإدخال.

هل يعمل البث المتدفق مع مكتبة Python SDK؟

نعم. مرر stream=True وكرّر عبر القطع. يُرسل الاستخدام في نهاية البث.

مفتاحك على بُعد استمارة تسجيل واحدة

أنشئ حساباً، وانسخ المفتاح، ثم غيّر URL الأساسي. هذا هو الإعداد كله.

احصل على مفتاح API