JA ▾
API キーを取得

PythonでのCharacter AI API:OpenAI SDKセットアップ

Character AI API Pythonワークフローを使用するには、公式のOpenAIパッケージをインストールし、そのbase URLをOpenAI互換のエンドポイントに設定し、モデルをuncensoredに設定します。このページの残りの部分では、履歴、ストリーミング、リトライ、コスト追跡を備えた小さなペルソナチャットを構築します。

プラットフォーム上のターミナルはストリーミングチャットバブルを表示し、リンクされたキューブにPythonチャットクライアントを表します

主要ポイント

  1. 標準SDKで変更される値は2つだけです:base_urlとapi_key。
  2. キャラクターの動作は、system messageと各ターンで再送信する履歴から生成されます。
  3. ストリーミング、ツール呼び出し、JSONモードはすべて同じクライアントを通じて機能します。
  4. HTTP 429を短い待機で処理し、フルキーでの同時呼び出しを8に制限します。

インストールと接続

専用のクライアントライブラリはありません。PythonのCharacterアプリは、他のすべてのものと同じ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)

挨拶とusageオブジェクトが出力された場合、接続は正常です。このサービスはPOST /v1/chat/completionsとGET /v1/modelsを公開しています。テキストチャット以外の画像、埋め込み、ファインチューニングは利用できません。

メモリ付きキャラクターチャットループ

APIはステートレスです。最後のターンを記憶しないため、プログラムは毎回会話全体を送信する必要があります。ペルソナの場合、system messageの後にユーザーとアシスタントのメッセージを交互に配置します。このループはそれらをリストに保持します。

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、および頻度ペナルティと存在ペナルティ。ロールプレイでは、temperatureが0.8〜1.0の範囲だと対話がより生き生きしますが、低い値は構造化されたタスクに適しています。類似の条件で2つのプロンプトバージョンを比較したい場合は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を呼び出します。キャラクターごとに、ユーザーごとに1つのファイルを持ち、すでにマルチキャラクターのセットアップが完了しています。ファイルの管理が困難になった場合でも、同じ辞書のリストは変更なしでデータベースの列やキーバリューストアに適合します。それはAPIが期待する内容そのものだからです。

何を保存するか考えてください。履歴にはユーザーが入力した個人情報が含まれる場合があります。このAPIに送信されるプロンプトはトレーニングに使用されませんが、独自のファイルとログはあなたの責任ですので、それらをどのくらいの期間保持し、誰がそれを読み取れるかを決定してください。

高価になる前に履歴をトリムする

コンテキストウィンドウは100,000トークンで、プロンプトとcompletionの合計です。長いロールプレイは時間とともにそれに達する可能性があり、コストは増加します。各ターンで履歴全体の入力トークンに対して課金されるためです。単純なアプローチは、system messageと最後の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語で要約させ、それらのメッセージをsystem message内のサマリーに置き換え、続行します。詳細は失われますがプロットスレッドは保持され、ターンごとのコストは一定に保たれます。

履歴が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になります。これはほとんどの会話の3分の1の価格です。

生成されるそばから返信をストリーミング

チャットインターフェースでは、テキストが生成されるそばから表示されるようにしたいものです。stream=Trueを設定し、チャンクをイテレートしてください。ストリーミングはサーバー送信イベント上で行われ、最後のチャンクでusageを要求できます。

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で複数のチャットを同時に実行する

同時に多くのユーザーを処理するWebサービスには非同期クライアントが必要です。パターンはシンプルです:1つの共有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())

20のジョブが作成されますが、一度に実行されるのは8つだけです。残りはセマフォ内で順番を待ちます。そのため、concurrencyエラーが発生することはありません。サービスがストリーミング返信を処理する場合、各オープンストリームは完了するまでカウントされることを覚えておいてください。つまり、クライアント側の遅いリーダーが予想以上にスロットを占有する可能性があります。クライアントにタイムアウトを設定し、ユーザーが離脱したストリームをキャンセルしてください。

1分あたりの制限は別です。フルキーで1分あたり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つの同時リクエストと1分あたり300リクエストを許容します。トライアルキーは2と60を許容します。制限を超えると、HTTP 429エラーコードrate_limited(1分あたりの数が多すぎる)または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")

1つのプロセスから多くの会話を実行する場合、セマフォでそれらを制限し、実行中のリクエストが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が含まれています。ストリーミングしてusageを要求する場合、最終チャンクにそれが含まれます。これらの数字を小さな関数でドルに変換し、セッション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()でモデルを1回だけリストしてください。その呼び出しが失敗した場合、ユーザーが知る前に間違ったキーまたは間違ったbase URLについて知ることができ、チャットループの奥深くにあるスタックトレースの代わりに明確なメッセージを出力できます。このコードをデプロイするチームは、多くの場合、同じ呼び出しをヘルスチェックルートに追加します。

セッションごとのコストをログに記録し、上位5パーセントを見てください。履歴を切り詰めない長いセッションは通常、請求書の大部分を占めます。その解決策は、前述の切り詰めまたは要約のアプローチです。

質問と回答

Character.aiの公式Pythonライブラリはありますか?

このサービスはCharacter.aiではなく、個別のライブラリも持っていません。上記のbase URLとモデルIDを使用して、標準のopenaiパッケージを使用します。

メッセージ間でキャラクターの一貫性を保つにはどうすればよいですか?

システムメッセージにペルソナを設定し、すべてのリクエストで直近の履歴を再送信してください。APIは会話を自動的に保存しません。

非同期クライアントは使用できますか?

はい。AsyncOpenAIは同じbase_urlとapi_keyを受け入れます。フルキーでは並列呼び出しを8に、トライアルキーでは2に制限してください。

チャット1ターンあたりのコストはいくらですか?

入力トークン1,500、出力トークン300の場合、1Mトークンあたり$0.15と$0.50に基づき、$0.000375となります。履歴が長くなると、入力の比率が増加します。

Python SDKでストリーミングは動作しますか?

はい。stream=Trueを指定し、チャンクをイテレートしてください。使用量はストリームの最後に送信されます。

キーはフォーム 1 つで手に入ります

アカウントを作成し、キーをコピーし、ベースURLを変更します。これでセットアップは完了です。

API キーを取得