TH ▾
รับคีย์ API

Character AI API ใน Python: การตั้งค่า OpenAI SDK

เพื่อใช้ workflow character ai api python ให้ติดตั้งแพ็กเกจ openai ทางการ ชี้ base URL ของมันไปยัง endpoint ที่เข้ากันได้กับ OpenAI และตั้งค่า model เป็น uncensored ส่วนที่เหลือของหน้านี้จะสร้าง persona chat ขนาดเล็กบนพื้นฐานนั้น โดยรวมประวัติ การสตรีมมิง การลองใหม่ และการติดตามต้นทุน

เทอร์มินัลบนแพลตฟอร์มที่สตรีมมิงฟองแชทเข้าสู่คิวบ์ที่เชื่อมโยงกัน ซึ่งแสดงถึงไคลเอนต์แชท Python

ประเด็นสำคัญ

  1. ค่าสองค่าที่เปลี่ยนแปลงใน SDK มาตรฐานคือ base_url และ api_key.
  2. พฤติกรรมของตัวละครมาจากข้อความระบบรวมกับประวัติที่คุณส่งใหม่ในแต่ละเทิร์น
  3. สตรีมมิง การเรียกใช้ฟังก์ชัน และโหมด JSON ทำงานผ่านไคลเอนต์ตัวเดียวกัน
  4. จัดการ HTTP 429 ด้วยระยะเวลาการรอแบบสั้น และจำกัดการเรียกพร้อมกันไว้ที่ 8 ครั้งต่อคีย์เต็ม

ติดตั้งและเชื่อมต่อ

ไม่มีไลบรารีไคลเอนต์เฉพาะ แอปพลิเคชัน Character ใน Python ใช้แพ็กเกจ openai เดียวกับส่วนอื่นๆ ติดตั้งและเก็บคีย์ของคุณใน environment variable

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 สิ่งที่ไม่ใช่แชทข้อความ เช่น รูปภาพ embedding หรือ fine-tuning ไม่พร้อมใช้งาน

ลูปแชทตัวละครพร้อมหน่วยความจำ

API เป็นแบบไร้สถานะ ไม่จำการสนทนาในรอบก่อนหน้า ดังนั้นโปรแกรมของคุณต้องส่งการสนทนาทั้งหมดทุกครั้ง สำหรับ persona หมายถึง 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)

การตั้งค่า sampling จะถูกส่งผ่านไปยังโมเดล: temperature, top_p, stop, seed และ frequency และ presence penalties สำหรับการ roleplay ค่า temperature ระหว่าง 0.8 ถึง 1.0 มักจะให้บทสนทนาที่มีชีวิตชีวา ในขณะที่ค่าที่ต่ำกว่าเหมาะสำหรับงานที่มีโครงสร้าง ตั้ง seed เมื่อต้องการเปรียบเทียบเวอร์ชันของ prompt สองเวอร์ชันภายใต้เงื่อนไขที่คล้ายกัน

บันทึกและโหลดการสนทนา

แชทที่หายไปเมื่อสคริปต์หยุดทำงานคือตัวอย่าง ไม่ใช่แอป การเก็บประวัติเป็นไฟล์ 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 หลังจากเพิ่มการตอบกลับของผู้ช่วย เก็บไฟล์แยกตามตัวละครและผู้ใช้ และคุณมีการตั้งค่าหลายตัวละครแล้ว เมื่อคุณเติบโตเกินกว่าไฟล์ รายการของ dict เหล่านี้จะเข้ากันได้กับคอลัมน์ฐานข้อมูลหรือที่เก็บ key-value โดยไม่ต้องเปลี่ยนแปลง เพราะเป็นสิ่งที่ API คาดหวังไว้

คิดเกี่ยวกับสิ่งที่คุณเก็บ ประวัติอาจมีรายละเอียดส่วนบุคคลที่ผู้ใช้ป้อนเข้ามา พรอมต์ที่ส่งไปยัง API นี้ไม่ถูกใช้ในการฝึก แต่ไฟล์และบันทึกของคุณเป็นความรับผิดชอบของคุณ ดังนั้นตัดสินใจว่าคุณเก็บข้อมูลไว้ยาวนานแค่ไหนและใครสามารถอ่านได้

ตัดประวัติออกก่อนที่ต้นทุนจะสูง

หน้าต่างบริบทมีขนาด 100,000 token รวม prompt และ completion บท roleplay ยาวๆ อาจถึงขีดจำกัดนี้เมื่อเวลาผ่านไป และต้นทุนจะเพิ่มขึ้นเนื่องจากคุณต้องจ่ายสำหรับ input token ของประวัติทั้งหมดในแต่ละเทิร์น วิธีง่ายๆ คือการเก็บ 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 และดำเนินการต่อ คุณอาจเสียรายละเอียดบางส่วนแต่รักษา plot threads ไว้ได้ และต้นทุนต่อเทิร์นจะคงที่

นี่คือคณิตศาสตร์สำหรับแชทที่มีประวัติ 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 และวนลูปผ่าน chunks การสตรีมมิงทำงานผ่าน server-sent events และคุณสามารถขอ usage ใน chunk สุดท้ายได้

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)

จำไว้ว่าคำขอที่สตรีมมิงจะถือ concurrency slot ไว้จนกว่าสตรีมมิงจะสิ้นสุด บนคีย์เต็มคุณสามารถรันได้ 8 ครั้งพร้อมกัน; บนคีย์ทดลองทำได้เพียง 2 ครั้ง หากผู้ใช้ปิดแท็บ ให้แน่ใจว่าเซิร์ฟเวอร์ของคุณปิดสตรีมมิง upstream ด้วย มิฉะนั้น slot จะยังคงถูกใช้งานอยู่

รันแชทจำนวนมากพร้อมกันด้วย asyncio

บริการเว็บที่จัดการผู้ใช้จำนวนมากในเวลาเดียวกันจำเป็นต้องใช้ไคลเอนต์ async รูปแบบนั้นเรียบง่าย: ไคลเอนต์ AsyncOpenAI ที่แชร์ร่วมกันหนึ่งตัว semaphore ที่มีขนาดเท่ากับขีดจำกัด concurrency ของคุณ และ 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())

สร้างงาน 20 งาน แต่รันได้เพียง 8 งานพร้อมกัน งานที่เหลือรอตาของตัวเองภายใน semaphore ดังนั้นคุณจะไม่เกิด concurrency error หากบริการของคุณจัดการการตอบกลับแบบสตรีมมิง จำไว้ว่าสตรีมมิงที่เปิดอยู่แต่ละรายการจะนับจนกว่าจะเสร็จสิ้น ซึ่งหมายความว่าผู้อ่านที่ช้าทางไคลเอนต์อาจถือ slot นานกว่าที่คุณคาดไว้ ตั้ง timeout บนไคลเอนต์และยกเลิกสตรีมมิงของผู้ใช้ที่หายไปแล้ว

ขีดจำกัดต่อนาทีนั้นแยกต่างหาก ที่ 300 คำขอต่อนาทีบนคีย์เต็ม การ burst ของ 20 คำขอสั้นๆ นั้นใช้ได้ผล แต่ลูปที่ส่งคำขอหลายพันรายการต้องการการควบคุมจังหวะ วิธีง่ายๆ คือการ sleep เป็นเศษเสี้ยวของวินาทีระหว่างการเริ่มงาน หรือใช้ไลบรารี token bucket ที่เข้ากับ stack ของคุณ

เครื่องมือและโหมด 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 โมเดลจะส่งคืน entry ของ 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)

ทดสอบสิ่งนี้กับ prompt ของคุณเองก่อนการนำไปใช้งานจริง โมเดลแบบ open-weight มีความแตกต่างกันในความสามารถในการปล่อย tool call อย่างน่าเชื่อถือ ดังนั้นให้เก็บเส้นทางสำรองไว้เมื่อ tool_calls เป็นค่าว่าง

จัดการข้อผิดพลาดและขีดจำกัดอัตรา

คีย์เต็มอนุญาตให้ทำคำขอพร้อมกัน 8 รายการและ 300 คำขอต่อนาที คีย์ทดลองอนุญาตให้ทำ 2 และ 60 เมื่อเกินขีดจำกัดคุณจะได้รับ HTTP 429 พร้อม error code rate_limited (คำขอมากเกินไปต่อนาที) หรือ concurrency (คำขอมากเกินไปพร้อมกัน) การ overload ชั่วคราวยังส่งคืน 429 พร้อม header Retry-After: 5 SDK จะ raise RateLimitError สำหรับกรณีเหล่านี้ และคุณสามารถห่อหุ้มการเรียกใช้ด้วย retry ได้

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

หากคุณรันการสนทนาจำนวนมากจาก process เดียว ให้จำกัดด้วย semaphore เพื่อไม่ให้มีคำขอที่กำลังประมวลผลเกิน 8 รายการ ด้วย asyncio และ AsyncOpenAI asyncio.Semaphore(8) รอบแต่ละการเรียกใช้ก็เพียงพอแล้ว response headers X-RateLimit-Limit-Requests และ X-RateLimit-Limit-Concurrency ยืนยันขีดจำกัดที่ใช้กับคีย์ของคุณ และ X-Balance-USD แสดงเครดิตที่เหลือของคุณ

คำขอที่ล้มเหลวหรือถูกปฏิเสธจะไม่ถูกเรียกเก็บเงิน ดังนั้นการ retry เมื่อเกิดข้อผิดพลาดจึงไม่เสียค่าใช้จ่าย เมื่อเครดิตของคุณเหลือน้อย ให้เติมเงินจาก $20 เป็น $500; จำนวนเงินตั้งแต่ $50 จะได้รับโบนัส 5%, 10% หรือ 15% ที่ระดับ $50, $100 และ $200 รายละเอียดอยู่ที่ หน้าราคา และรายการพารามิเตอร์เต็มอยู่ใน เอกสาร

ติดตามต้นทุนของแต่ละเซสชัน

การตอบกลับทุกแบบที่ไม่ใช่สตรีมมิงจะมีวัตถุ usage พร้อม prompt_tokens และ completion_tokens เมื่อคุณสตรีมมิงและขอ usage chunk สุดท้ายจะบรรจุข้อมูลนั้น แปลงตัวเลขเหล่านั้นเป็นดอลลาร์ด้วยฟังก์ชันขนาดเล็กและ log ไว้ถัดจาก session 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 input token และ 250 output token ต่อ reply ค่าเฉลี่ยของ input คือประมาณ 3,250 token ค่า input ต่อเทิร์นคือประมาณ 3,250 x $0.15 / 1,000,000 = $0.00049 และ output คือ 250 x $0.50 / 1,000,000 = $0.000125 ดังนั้นโดยประมาณ $0.00061 ต่อเทิร์น และ $0.0245 สำหรับ 40 เทิร์น ผู้ใช้ที่เล่น 20 เซสชันต่อเดือนทำให้คุณเสียค่าใช้จ่ายประมาณ 49 เซนต์ นั่นคือตัวเลขที่คุณสามารถกำหนดราคาผลิตภัณฑ์ได้

รันการตรวจสอบการเชื่อมต่อภายใน virtual environment เพื่อให้เวอร์ชันแพ็กเกจคงที่สำหรับโปรเจกต์ และแสดงรายการโมเดลครั้งเดียวด้วย client.models.list() เมื่อเริ่มต้น หากการเรียกใช้นั้นล้มเหลว คุณจะทราบเกี่ยวกับคีย์ผิดหรือ base URL ผิดก่อนที่ผู้ใช้จะพบปัญหา และคุณสามารถพิมพ์ข้อความที่ชัดเจนแทน stack trace ลึกภายใน chat loop ทีมที่ deploy โค้ดนี้มักเพิ่มการเรียกใช้เดียวกันไปยัง health check route

บันทึกต้นทุนต่อเซสชันและดูที่ห้าเปอร์เซ็นต์สูงสุด เซสชันที่ยาวนานซึ่งไม่เคยตัดประวัติการสนทนาออกมักจะครองบิลส่วนใหญ่ และวิธีแก้ไขคือวิธีการตัดหรือสรุปตามที่อธิบายไว้ก่อนหน้านี้

ถาม-ตอบ

มีไลบรารี Python อย่างเป็นทางการสำหรับ Character.ai หรือไม่?

บริการนี้ไม่ใช่ Character.ai และไม่มีไลบรารีแยกต่างหาก คุณใช้แพ็คเกจ openai มาตรฐานพร้อม base URL และ model ID ที่ระบุไว้ข้างต้น

ฉันจะรักษาตัวละครให้สอดคล้องกันข้ามข้อความได้อย่างไร?

ใส่บุคลิกภาพลงในข้อความระบบและส่งประวัติการสนทนาล่าสุดซ้ำพร้อมคำขอทุกครั้ง API ไม่ได้จัดเก็บการสนทนาให้คุณ

ฉันสามารถใช้ไคลเอนต์ async ได้หรือไม่?

ใช่ AsyncOpenAI ยอมรับ base_url และ api_key เดียวกัน จำกัดการเรียกพร้อมกันเป็น 8 บนคีย์เต็มหรือ 2 บนคีย์ทดลอง

หนึ่งรอบแชทคิดเงินเท่าไหร่?

ด้วย 1,500 input token และ 300 output token คือ $0.000375 โดยอิงจาก $0.15 และ $0.50 ต่อ 1M token ประวัติที่ยาวขึ้นเพิ่ม input share

SDK Python รองรับ streaming หรือไม่?

ใช่ ส่ง stream=True และวนซ้ำผ่าน chunks Usage จะถูกส่งที่ท้าย stream

คีย์ของคุณอยู่ห่างแค่แบบฟอร์มเดียว

สร้างบัญชี คัดลอกคีย์ และเปลี่ยน base URL นั่นคือการตั้งค่าทั้งหมด

รับคีย์ API