VI ▾
Lấy khóa API

API Character AI bằng Python: Thiết lập SDK OpenAI

Để sử dụng quy trình API Character AI bằng Python, hãy cài đặt gói openai chính thức, trỏ base URL của nó vào một endpoint tương thích OpenAI và đặt mô hình thành uncensored. Phần còn lại của trang này xây dựng một ứng dụng chat nhân vật nhỏ dựa trên đó, bao gồm lịch sử, streaming, thử lại và theo dõi chi phí.

Terminal trên nền tảng phát trực tiếp các bong bóng trò chuyện vào các khối liên kết, đại diện cho một ứng dụng trò chuyện Python

Điểm chính

  1. Hai giá trị thay đổi trong SDK tiêu chuẩn: base_url và api_key.
  2. Hành vi của nhân vật đến từ system message cùng với lịch sử bạn gửi lại mỗi lượt.
  3. Streaming, gọi hàm và chế độ JSON đều hoạt động thông qua cùng một client.
  4. Xử lý HTTP 429 bằng cách chờ một khoảng thời gian ngắn và giới hạn gọi đồng thời ở mức 8 với khóa đầy đủ.

Cài đặt và kết nối

Không có thư viện client đặc biệt. Các ứng dụng Character AI bằng Python sử dụng cùng gói openai như mọi thứ khác. Hãy cài đặt nó và giữ khóa của bạn trong một biến môi trường.

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

Lấy khóa từ trang khóa API trước tiên. Tài khoản mới có thể nhận $0,50 tín dụng dùng thử chỉ với một cú nhấp chuột, không cần thẻ. Sau đó tạo client:

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)

Nếu lệnh đó in ra lời chào và một đối tượng usage, kết nối đã ổn. Dịch vụ cung cấp POST /v1/chat/completions và GET /v1/models. Những tính năng không phải chat văn bản, như hình ảnh, embedding hoặc fine-tuning, đều không khả dụng.

Vòng lặp chat nhân vật có bộ nhớ

API không có trạng thái. Nó không nhớ lượt trước đó, vì vậy chương trình của bạn phải gửi toàn bộ cuộc hội thoại mỗi lần. Đối với một nhân vật, điều đó có nghĩa là một system message theo sau là các tin nhắn user và assistant xen kẽ. Vòng lặp này giữ chúng trong một danh sách.

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)

Các cài đặt sampling được truyền trực tiếp đến mô hình: temperature, top_p, stop, seed và các hình phạt về tần suất và sự hiện diện. Đối với nhập vai, temperature từ 0,8 đến 1,0 thường mang lại hội thoại sống động hơn, trong khi giá trị thấp hơn phù hợp với các tác vụ có cấu trúc. Đặt seed khi bạn muốn so sánh hai phiên bản prompt trong các điều kiện tương tự.

Lưu và tải lại một cuộc hội thoại

Một cuộc chat biến mất khi script thoát ra là bản demo, không phải ứng dụng. Lưu trữ lịch sử dưới dạng tệp JSON là bước nhỏ nhất giúp nó cảm thấy tồn tại lâu dài. Hàm hỗ trợ bên dưới tải các tin nhắn đã lưu của nhân vật nếu chúng tồn tại và ghi lại chúng sau mỗi lượt.

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

Gọi load khi khởi động và save sau khi bạn thêm phản hồi của assistant. Hãy giữ một tệp cho mỗi nhân vật và mỗi người dùng, và bạn đã có một thiết lập đa nhân vật. Khi bạn vượt quá khả năng của tệp, cùng danh sách các dict này phù hợp với một cột cơ sở dữ liệu hoặc một kho lưu trữ khóa-giá trị mà không cần thay đổi, vì nó chính xác là những gì API mong đợi.

Hãy suy nghĩ về những gì bạn lưu trữ. Lịch sử có thể chứa các chi tiết cá nhân mà người dùng đã nhập. Các prompt gửi đến API này không được sử dụng để huấn luyện, nhưng các tệp và nhật ký của riêng bạn là trách nhiệm của bạn, vì vậy hãy quyết định bạn giữ chúng trong bao lâu và ai có thể đọc chúng.

Cắt ngắn lịch sử trước khi nó đắt đỏ

Cửa sổ ngữ cảnh là 100.000 token, bao gồm prompt và completion. Một cuộc nhập vai dài có thể đạt đến giới hạn đó theo thời gian, và chi phí tăng lên vì bạn phải trả tiền cho token đầu vào cho toàn bộ lịch sử trong mỗi lượt. Một cách tiếp cận đơn giản là giữ lại system message và N lượt trao đổi cuối cùng.

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

Một thiết kế tốt hơn cho các câu chuyện dài là tóm tắt cuốn chiếu (rolling summary). Cứ sau 30 tin nhắn, hãy yêu cầu mô hình tóm tắt phần cũ hơn trong 200 từ, thay thế những tin nhắn đó bằng bản tóm tắt bên trong system message và tiếp tục. Bạn sẽ mất một số chi tiết nhưng giữ được các mạch truyện, và chi phí mỗi lượt vẫn giữ nguyên.

Đây là phép tính cho một cuộc chat đã đạt 8.000 token lịch sử với phản hồi 300 token: đầu vào là 8.000 x $0,15 / 1.000.000 = $0,0012, đầu ra là 300 x $0,50 / 1.000.000 = $0,00015, vậy $0,00135 cho mỗi lượt. Cắt ngắn lịch sử đó xuống còn 2.000 token làm giảm lượt xuống còn $0,0003 + $0,00015 = $0,00045. Đó là một phần ba giá cho hầu hết các cuộc hội thoại.

Truyền phát câu trả lời khi chúng được viết

Đối với giao diện chat, bạn muốn văn bản xuất hiện khi nó được tạo. Đặt stream=True và lặp qua các chunk. Streaming chạy qua các sự kiện do máy chủ gửi, và bạn có thể yêu cầu dữ liệu sử dụng trong chunk cuối cùng.

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)

Hãy nhớ rằng một yêu cầu streaming giữ slot concurrency của nó cho đến khi stream kết thúc. Với khóa đầy đủ, bạn có thể chạy 8 cùng lúc; với khóa dùng thử chỉ 2. Nếu người dùng đóng tab, hãy đảm bảo máy chủ của bạn cũng đóng stream upstream, nếu không nó sẽ giữ slot bận.

Chạy nhiều chat cùng lúc với asyncio

Một dịch vụ web xử lý nhiều người dùng cùng lúc cần client bất đồng bộ. Mẫu đơn giản là: một client AsyncOpenAI dùng chung, một semaphore có kích thước bằng giới hạn concurrency của bạn, và một coroutine cho mỗi cuộc hội thoại.

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

Hai mươi công việc được tạo ra, nhưng chỉ tám chạy cùng lúc. Số còn lại chờ lượt trong semaphore, vì vậy bạn không bao giờ kích hoạt lỗi concurrency. Nếu dịch vụ của bạn xử lý các phản hồi streaming, hãy nhớ rằng mỗi stream mở tính cho đến khi nó kết thúc, điều đó có nghĩa là những người đọc chậm ở phía client có thể giữ slot lâu hơn bạn mong đợi. Đặt thời gian chờ trên client và hủy các stream mà người dùng đã rời đi.

Giới hạn mỗi phút là riêng biệt. Ở mức 300 yêu cầu mỗi phút với khóa đầy đủ, một đợt 20 lệnh gọi ngắn là ổn, nhưng một vòng lặp gửi hàng nghìn lệnh gọi cần được điều chỉnh tốc độ. Một cách tiếp cận đơn giản là tạm dừng (sleep) trong một phần giây giữa các lần khởi chạy tác vụ, hoặc sử dụng thư viện token bucket phù hợp với ngăn xếp của bạn.

Công cụ và chế độ JSON

Các bot nhân vật thường cần đầu ra có cấu trúc: điểm cảm xúc, cập nhật kho đồ, danh sách lựa chọn cho người chơi. Chế độ JSON làm cho phản hồi hợp lệ JSON, và bạn mô tả hình dạng trong prompt.

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

Gọi hàm sử dụng các trường tools và tool_choice tiêu chuẩn. Mô hình trả về một mục tool_calls, mã của bạn chạy hàm và gửi kết quả lại dưới dạng tin nhắn với 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)

Hãy kiểm tra điều này với các prompt của riêng bạn trước khi dựa vào nó. Các mô hình open-weight khác nhau về độ tin cậy khi phát ra một lệnh gọi công cụ, vì vậy hãy giữ một đường dự phòng khi tool_calls trống.

Xử lý lỗi và giới hạn tốc độ

Khóa đầy đủ cho phép 8 yêu cầu đồng thời và 300 yêu cầu mỗi phút. Khóa dùng thử cho phép 2 và 60. Vượt quá giới hạn, bạn nhận được HTTP 429 với mã lỗi rate_limited (quá nhiều mỗi phút) hoặc concurrency (quá nhiều cùng lúc). Quá tải tạm thời cũng trả về 429, với tiêu đề Retry-After: 5. SDK ném RateLimitError cho những trường hợp này, và bạn có thể bao bọc lệnh gọi trong một lần thử lại.

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

Nếu bạn chạy nhiều cuộc hội thoại từ một quy trình, hãy giới hạn chúng bằng một semaphore để bạn không bao giờ vượt quá 8 yêu cầu đang xử lý. Với asyncio và AsyncOpenAI, asyncio.Semaphore(8) xung quanh mỗi lệnh gọi là đủ. Các tiêu đề phản hồi X-RateLimit-Limit-Requests và X-RateLimit-Limit-Concurrency xác nhận các giới hạn áp dụng cho khóa của bạn, và X-Balance-USD hiển thị tín dụng còn lại của bạn.

Các yêu cầu thất bại hoặc bị từ chối không bị tính phí, vì vậy các lần thử lại khi gặp lỗi không tốn chi phí của bạn. Khi số dư của bạn thấp, hãy nạp tiền từ $20 đến $500; các khoản từ $50 trở lên nhận thêm thưởng 5%, 10% hoặc 15% ở mức $50, $100 và $200. Chi tiết có trên trang giá cả, và danh sách đầy đủ các tham số có trong tài liệu.

Theo dõi chi phí của mỗi phiên

Mọi phản hồi không streaming đều bao gồm một đối tượng usage với prompt_tokens và completion_tokens. Khi bạn streaming và yêu cầu dữ liệu sử dụng, chunk cuối cùng sẽ mang nó. Chuyển những con số đó sang đô la bằng một hàm nhỏ và ghi lại nó bên cạnh ID phiên.

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

Với những con số này, bạn có thể trả lời các câu hỏi thực tế. Nếu một phiên trung bình là 40 lượt, với lịch sử tăng từ 500 lên 6.000 token đầu vào và 250 token đầu ra cho mỗi phản hồi, đầu vào trung bình là khoảng 3.250 token. Chi phí đầu vào cho mỗi lượt là khoảng 3.250 x $0,15 / 1.000.000 = $0,00049 và đầu ra là 250 x $0,50 / 1.000.000 = $0,000125, vậy khoảng $0,00061 cho mỗi lượt và $0,0245 cho 40 lượt. Một người dùng chơi 20 phiên một tháng tốn cho bạn khoảng 49 cent. Đó là một con số bạn có thể định giá sản phẩm xung quanh.

Chạy kiểm tra kết nối trong môi trường ảo để phiên bản gói được giữ cố định cho dự án, và liệt kê các mô hình một lần với client.models.list() khi khởi động. Nếu lệnh gọi đó thất bại, bạn sẽ biết về khóa sai hoặc base URL sai trước khi bất kỳ người dùng nào làm vậy, và bạn có thể in một thông báo rõ ràng thay vì một ngăn xếp lệnh gọi sâu bên trong một vòng lặp chat. Các nhóm triển khai mã này thường thêm cùng lệnh gọi vào một tuyến kiểm tra sức khỏe.

Hãy ghi lại chi phí cho mỗi phiên và xem xét năm phần trăm cao nhất. Các phiên dài không bao giờ cắt ngắn lịch sử thường chiếm ưu thế trong hóa đơn, và giải pháp là phương pháp cắt ngắn hoặc tóm tắt đã mô tả ở trên.

Hỏi đáp

Có thư viện Python chính thức cho Character.ai không?

Dịch vụ này không phải Character.ai và không có thư viện riêng. Bạn sử dụng gói openai tiêu chuẩn với base URL và model ID đã nêu ở trên.

Làm sao để giữ tính cách nhân vật nhất quán qua các tin nhắn?

Đặt nhân vật vào tin nhắn hệ thống và gửi lại lịch sử gần đây với mỗi yêu cầu. API không lưu trữ cuộc trò chuyện cho bạn.

Tôi có thể dùng client bất đồng bộ không?

Có. AsyncOpenAI chấp nhận cùng base_url và api_key. Giới hạn các lệnh gọi đồng thời ở mức 8 với khóa đầy đủ hoặc 2 với khóa dùng thử.

Một lượt trò chuyện tốn bao nhiêu?

Với 1.500 token đầu vào và 300 token đầu ra, chi phí là $0,000375, dựa trên giá $0,15 và $0,50 cho mỗi 1 triệu token. Lịch sử dài hơn làm tăng tỷ trọng token đầu vào.

Truyền phát (streaming) có hoạt động với SDK Python không?

Có. Truyền stream=True và lặp qua các chunk. Việc sử dụng được gửi ở cuối luồng truyền phát.

Khóa của bạn chỉ cách một biểu mẫu

Tạo tài khoản, sao chép khóa, thay đổi base URL. Đó là toàn bộ thiết lập.

Lấy khóa API