API Character AI w Pythonie: konfiguracja SDK OpenAI
Aby uruchomić workflow Pythona dla Character AI, zainstaluj oficjalny pakiet openai, ustaw jego Base URL na endpoint kompatybilny z OpenAI i ustaw model na uncensored. Reszta tej strony pokazuje, jak zbudować prosty czat z osobowością na tej bazie, z historią, strumieniowaniem, ponowieniami w przypadku błędów i śledzeniem kosztów.
Zaktualizowano

Kluczowe punkty
- W standardowym SDK zmieniają się dwie wartości: base_url i api_key.
- Zachowanie postaci wynika z wiadomości systemowej plus historii, którą wysyłasz ponownie w każdej turze.
- Strumieniowanie, wywoływanie funkcji i tryb JSON działają przez tego samego klienta.
- Obsługuj HTTP 429 krótkim oczekiwaniem i ogranicz równoległe wywołania do 8 przy pełnym kluczu.
Zainstaluj i podłącz
Nie ma specjalnej biblioteki klienta. Aplikacje Character w Pythonie używają tego samego pakietu openai co wszystko inne. Zainstaluj go i przechowuj swój klucz w zmiennej środowiskowej.
pip install openai
export API_KEY="paste-your-key-here"Najpierw uzyskaj klucz na stronie kluczy API. Nowe konta mogą jednym kliknięciem uzyskać darmowy kredyt próbny w wysokości $0,50 bez potrzeby podawania karty. Następnie utwórz klienta:
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)Jeśli wyświetli się powitanie i obiekt użycia, połączenie jest poprawne. Usługa udostępnia POST /v1/chat/completions i GET /v1/models. Wszystko, co nie jest czatem tekstowym, np. obrazy, embeddingi czy fine-tuning, nie jest dostępne.
Pętla czatu z postacią i pamięcią
API jest bezstanowe. Nie pamięta ostatniej tury, więc Twój program musi wysyłać całą rozmowę za każdym razem. Dla osobowości oznacza to wiadomość systemową, po której następują naprzemiennie wiadomości użytkownika i asystenta. Ta pętla utrzymuje je na liście.
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)Ustawienia próbkowania są przekazywane do modelu: temperature, top_p, stop, seed oraz kary częstotliwości i obecności. Dla odgrywania ról temperatura między 0,8 a 1,0 zazwyczaj daje żywszą rozmowę, podczas gdy niższa wartość pasuje do zadań strukturalnych. Ustaw seed, gdy chcesz porównać dwie wersje promptu w podobnych warunkach.
Zapisz i wczytaj rozmowę
Czat, który znika po zakończeniu skryptu, to demonstracja, nie aplikacja. Przechowywanie historii jako pliku JSON to najmniejszy krok, który sprawia, że czat wydaje się trwały. Poniższa pomocnicza funkcja ładuje zapisane wiadomości postaci, jeśli istnieją, i zapisuje je z powrotem po każdej turze.
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))Wywołaj load przy starcie i save po dodaniu odpowiedzi asystenta. Trzymaj jeden plik na postać i na użytkownika, a już masz konfigurację dla wielu postaci. Gdy wyczerpiesz możliwości plików, ta sama lista słowników pasuje do kolumny bazy danych lub magazynu klucz-wartość bez zmian, ponieważ jest dokładnie tym, czego oczekuje API.
Zastanów się, co przechowujesz. Historia może zawierać szczegóły osobowe wpisane przez użytkowników. Prompty wysłane do tego API nie są używane do trenowania, ale Twoje własne pliki i logi są Twoją odpowiedzialnością, więc zdecyduj, jak długo je przechowujesz i kto może je czytać.
Obcinaj historię, zanim stanie się droga
Okno kontekstu ma 100 000 tokenów, łącznie z promptem i uzupełnieniem. Długa gra fabularna może osiągnąć ten limit z czasem, a koszt rośnie, ponieważ płacisz za tokeny wejściowe za pełną historię przy każdej turze. Proste podejście przechowuje wiadomość systemową i ostatnie N wymian.
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),
)Lepszym rozwiązaniem dla długich historii jest toczące się podsumowanie. Co 30 wiadomości poproś model o podsumowanie starszej części w 200 słowach, zastąp te wiadomości podsumowaniem w wiadomości systemowej i kontynuuj. Tracisz nieco szczegółów, ale zachowujesz wątki fabularne, a koszt na turę pozostaje stały.
Oto matematyka dla czatu, który osiągnął 8000 tokenów historii z odpowiedzią 300 tokenów: wejście to 8000 x $0,15 / 1 000 000 = $0,0012, wyjście to 300 x $0,50 / 1 000 000 = $0,00015, więc $0,00135 na turę. Obcięcie tej historii do 2000 tokenów obniża koszt tury do $0,0003 + $0,00015 = $0,00045. To jedna trzecia ceny dla większości rozmów.
Strumieniuj odpowiedzi, gdy są pisane
W interfejsie czatu chcesz, aby tekst pojawiał się w miarę generowania. Ustaw stream=True i iteruj po fragmentach. Strumieniowanie działa za pomocą zdarzeń wysyłanych przez serwer (SSE), a możesz poprosić o informacje o użyciu w ostatnim fragmencie.
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)Pamiętaj, że żądanie strumieniowe zajmuje slot współbieżności do końca strumienia. Dla pełnego klucza możesz uruchomić 8 naraz; dla klucza próbnego tylko 2. Jeśli użytkownik zamknie kartę, upewnij się, że Twój serwer zamyka również strumień nadrzędny, w przeciwnym razie slot pozostanie zajęty.
Uruchamiaj wiele czatów jednocześnie z asyncio
Usługa internetowa obsługująca wielu użytkowników jednocześnie potrzebuje klienta asynchronicznego. Wzorzec jest prosty: jeden współdzielony klient AsyncOpenAI, jeden semafor wielkości Twojego limitu równoległości i korutyna na rozmowę.
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())Tworzone są dwadzieście zadań, ale jednocześnie uruchamiane są tylko osiem. Pozostałe czekają na swoją kolej w semaforze, więc nigdy nie wywołasz błędu concurrency. Jeśli Twoja usługa obsługuje strumieniowane odpowiedzi, pamiętaj, że każdy otwarty strumień liczy się do zakończenia, co oznacza, że wolni odbiorcy po stronie klienta mogą zajmować sloty dłużej, niż się spodziewasz. Ustaw limit czasu na kliencie i anuluj strumienie użytkowników, którzy już odeszli.
Limit na minutę jest osobny. Przy 300 zapytaniach na minutę przy pełnym kluczu, skok 20 krótkich wywołań jest OK, ale pętla wysyłająca tysiące wywołań potrzebuje tempa. Prostym podejściem jest uśpienie na ułamek sekundy między uruchomieniami zadań lub użycie biblioteki token bucket, która pasuje do Twojego stosu.
Narzędzia i tryb JSON
Boty postaci często potrzebują danych strukturalnych: wynik nastroju, aktualizacja ekwipunku, lista wyborów dla gracza. Tryb JSON sprawia, że odpowiedź jest poprawnym JSON, a Ty opisujesz kształt w prompcie.
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"])Wywoływanie narzędzi używa standardowych pól tools i tool_choice. Model zwraca wpis tool_calls, Twój kod wykonuje funkcję, a Ty wysyłasz wynik z powrotem jako wiadomość z 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)Przetestuj to na swoich promptach przed poleganiem na tym. Modele o otwartych wagach różnią się pod względem niezawodności emitowania wywołania narzędzia, więc zachowaj ścieżkę awaryjną, gdy tool_calls jest puste.
Obsługuj błędy i limity zapytań
Pełny klucz pozwala na 8 równoległych zapytań i 300 zapytań na minutę. Klucz próbny pozwala na 2 i 60. Po przekroczeniu limitu otrzymasz HTTP 429 z kodem błędu rate_limited (zbyt wiele na minutę) lub concurrency (zbyt wiele jednocześnie). Tymczasowe przeciążenie również zwraca 429, z nagłówkiem Retry-After: 5. SDK podnosi RateLimitError dla tych przypadków, a Ty możesz opakować wywołanie w ponowienie.
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")Jeśli uruchamiasz wiele rozmów z jednego procesu, ogranicz je semaforem, aby nigdy nie przekroczyć 8 zapytań w locie. Z asyncio i AsyncOpenAI, asyncio.Semaphore(8) wokół każdego wywołania wystarczy. Nagłówki odpowiedzi X-RateLimit-Limit-Requests i X-RateLimit-Limit-Concurrency potwierdzają limity obowiązujące dla Twojego klucza, a X-Balance-USD pokazuje Twój pozostały kredyt.
Nieudane lub odrzucone zapytania nie są rozliczane, więc ponowne próby po błędach nie kosztują Cię więcej. Gdy stan konta spada, doładuj go kwotą od $20 do $500; kwoty od $50 dają bonus 5%, 10% lub 15% na poziomach $50, $100 i $200. Szczegóły znajdziesz na stronie z cenami, a pełną listę parametrów w dokumentacji.
Śledź koszty każdej sesji
Każda odpowiedź niestrumieniowana zawiera obiekt usage z polami prompt_tokens i completion_tokens. Gdy korzystasz ze strumieniowania i poprosisz o użycie, ostatni fragment je zawiera. Zamień te liczby na dolary za pomocą małej funkcji i zaloguj je obok identyfikatora sesji.
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}")Dzięki tym liczbom możesz odpowiedzieć na praktyczne pytania. Jeśli średnia sesja ma 40 tur, z historią rosnącą od 500 do 6000 tokenów wejściowych i 250 tokenów wyjściowych na odpowiedź, średnie wejście to około 3250 tokenów. Koszt wejścia na turę to około 3250 x $0,15 / 1 000 000 = $0,00049, a wyjście to 250 x $0,50 / 1 000 000 = $0,000125, więc około $0,00061 na turę i $0,0245 za 40 tur. Użytkownik, który gra 20 sesji miesięcznie, kosztuje Cię około 49 centów. To liczba, wokół której możesz ustalić cenę produktu.
Uruchom test połączenia w środowisku wirtualnym, aby wersja pakietu była stała dla projektu, i wypisz modele raz na starcie za pomocą client.models.list(). Jeśli to wywołanie się nie powiedzie, dowiesz się o błędnym kluczu lub złym Base URL zanim zrobi to użytkownik, i możesz wyświetlić jasny komunikat zamiast śladu stosu głęboko w pętli czatu. Zespoły wdrażające ten kod często dodają to samo wywołanie do trasy kontroli stanu.
Zaloguj koszt na sesję i spójrz na górne pięć procent. Długie sesje, które nigdy nie obcinają historii, zwykle dominują w rachunku, a rozwiązaniem jest obcinanie lub podejście podsumowania opisane wcześniej.