tavern-labs-ai/character-ai-sdk

选用指南

AI 根据 README 整理 · 2026/11/1 00:46:43

适用场景

适用于需要角色一致性及跨会话记忆的聊天、语音、游戏或 HTTP 服务等场景。

查看 README 依据

| Interface | Chat, voice, game, HTTP service, or SillyTavern | ✓ | The persona catalog and runtime share one versioned package, so applications can adopt a bundled character without coupling its identity or memory to one provider. --- ## How it fits together ```mermaid flowchart LR Cards[Persona cards · atlas · sage · …] --> Manifest[Persona manifest] UI[Chat · Voice · Game · SillyTavern] --> Runtime[Persona Runtime] Runtime --> Compiler[Persona Compiler] Runtime --> Recall[Memory Recall] Runtime --> Model[Character Model]

使用方式

通过 npm 安装后，以代码方式导入并使用，支持 OpenAI 和 Amazon Bedrock 作为模型提供商。

查看 README 依据

- An OpenAI API key **or** AWS credentials with Bedrock model access - `better-sqlite3` when using the SQLite adapter ### Install ```bash npm install character-ai-sdk ``` From a source checkout: ```bash npm install npm run build ``` ### 1. Pick a persona ```js import { getPersona, listPersonas, DEFAULT_PERSONAS } from "character-ai-sdk"; // the two personas used in Tavern Labs demos const atlas = getPersona("atlas"); const sage = getPersona("sage"); console.log("defaults:", DEFAULT_PERSONAS.join(", ")); // or see everything in the SDK for (const p of listPersonas()) {

"author": "Tavern Labs" } ``` Traits are advisory: pass them alongside the system prompt so a host application can adapt tone without rewriting the prompt. Treat returned cards as immutable shared catalog data. A card's `suggestedModel` is a recommendation, not a guarantee that the model is enabled in your provider account or region. --- ## Choose your stack ### OpenAI ```js import { createOpenAICharacterModel, createOpenAIEmbeddings, createOpenAIExtractor, } from "character-ai-sdk/openai"; ```

The adapters use the Responses API for extraction and character generation and the Embeddings API for vectors. Specify model IDs explicitly so a package upgrade never changes model behavior. ### Amazon Bedrock ```js import { createBedrockCharacterModel, createBedrockExtractor, createBedrockTitanEmbeddings, } from "character-ai-sdk/bedrock"; const region = process.env.AWS_REGION ?? "us-east-1"; const modelId = process.env.BEDROCK_MODEL_ID; if (!modelId) throw new Error("BEDROCK_MODEL_ID is required"); const adapters = { extractor: createBedrockExtractor({ region, modelId }),

部署要求

需要 Node.js 20 或更高版本，以及 OpenAI API 密钥或具有 Bedrock 模型访问权限的 AWS 凭证；使用 SQLite 适配器时需安装 better-sqlite3。

查看 README 依据

Model --> OA[OpenAI] Model --> BR[Amazon Bedrock] Recall --> Store[(Memory Store)] Runtime --> Ingest[Memory Extraction] Ingest --> Store Store --> MEM[In-memory] Store --> JSON[Atomic JSON] Store --> SQL[SQLite] ``` The persona runtime recalls relevant memories, compiles character instructions, asks a model for the next response, ingests the completed turn, evolves relationship state, and returns both text and voice delivery metadata. --- ## Quick start ### Requirements - Node.js 20 or newer

- An OpenAI API key **or** AWS credentials with Bedrock model access - `better-sqlite3` when using the SQLite adapter ### Install ```bash npm install character-ai-sdk ``` From a source checkout: ```bash npm install npm run build ``` ### 1. Pick a persona ```js import { getPersona, listPersonas, DEFAULT_PERSONAS } from "character-ai-sdk"; // the two personas used in Tavern Labs demos const atlas = getPersona("atlas"); const sage = getPersona("sage"); console.log("defaults:", DEFAULT_PERSONAS.join(", ")); // or see everything in the SDK for (const p of listPersonas()) {

已知限制

人设卡片的 suggestedModel 仅为建议，不保证在您的提供商账户或区域中可用。

查看 README 依据

"author": "Tavern Labs" } ``` Traits are advisory: pass them alongside the system prompt so a host application can adapt tone without rewriting the prompt. Treat returned cards as immutable shared catalog data. A card's `suggestedModel` is a recommendation, not a guarantee that the model is enabled in your provider account or region. --- ## Choose your stack ### OpenAI ```js import { createOpenAICharacterModel, createOpenAIEmbeddings, createOpenAIExtractor, } from "character-ai-sdk/openai"; ```