酒馆助手

Appearance

请求生成 ​

提示

请务必先阅读如何正确使用酒馆助手

酒馆助手提供了函数用于更加灵活地请求 AI 生成回复，你可以通过它来自定义生成时要采用的提示词配置。 点击查看对应类型定义文件（可发给 AI 或 IDE 使用，酒馆助手设置中提供了打包下载）

注意

目前仅支持聊天补全（Chat Completion）。

generate ​

使用 Silly Tavern 当前启用的预设，让 AI 生成一段文本。

typescript
function generate(config: GenerateConfig): Promise<string>;
typescript
type GenerateConfig = {
  /** 用户输入 */
  user_input?: string;

  /**
   * 图片输入，支持以下格式：
   * - File 对象：通过 input[type="file"] 获取的文件对象
   * - Base64 字符串：图片的 base64 编码
   * - URL 字符串：图片的在线地址
   */
  image?: File | string | (File | string)[];

  /**
   * 是否启用流式传输; 默认为 `false`.
   *
   * 若启用流式传输, 每次得到流式传输结果时, 函数将会发送事件:
   * - `iframe_events.STREAM_TOKEN_RECEIVED_FULLY`: 监听它可以得到流式传输的当前完整文本 ("这是", "这是一条", "这是一条流式传输")
   * - `iframe_events.STREAM_TOKEN_RECEIVED_INCREMENTALLY`: 监听它可以得到流式传输的当前增量文本 ("这是", "一条", "流式传输")
   *
   * @example
   * eventOn(iframe_events.STREAM_TOKEN_RECEIVED_FULLY, text => console.info(text));
   */
  should_stream?: boolean;

  /**
   * 覆盖选项. 若设置, 则 `overrides` 中给出的字段将会覆盖对应的提示词.
   *   如 `overrides.char_description = '覆盖的角色描述';` 将会覆盖角色描述.
   */
  overrides?: Overrides;

  /** 要额外注入的提示词 */
  injects?: Omit<InjectionPrompt, 'id'>[];

  /** 最多使用多少条聊天历史; 默认为 'all' */
  max_chat_history?: 'all' | number;

  /** 自定义API配置 */
  custom_api?: CustomApiConfig;

  /**
   * 唯一id
   *
   * 可以并发生成，并可以通过stopGenerateById停止特定生成，不设置默认生成uuid，在发送的事件中也会返回该id
   */
  generation_id?: string;
};

参数 ​

generation_id? ​

  • 类型: string
  • 描述: 生成 ID。如果设置，可以通过事件监听接收某一特定请求的生成结果。以及中止特定id的请求。具体见函数的事件发送，不提供时，则使用随机uuid作为id。

user_input? ​

  • 类型: string
  • 描述: 用户输入

should_stream? ​

  • 类型: boolean
  • 描述: 是否启用流式传输；默认为 false。启用流式传输后，可以接收到额外的事件，通过参数获得传输过程的完整/增量文本。具体见函数的事件发送

image? ​

  • 类型: File|string[]
  • 描述: 图片输入，支持以数组形式输入多张图片：
    • File 对象：通过 input[type="file"] 获取的文件对象
    • Base64 字符串：图片的 base64 编码
    • URL 字符串：图片的在线地址

custom_api? ​

overrides? ​

  • 类型: Overrides
  • 描述: 覆盖选项。若设置, 则 overrides 中给出的字段将会覆盖对应的提示词。如 overrides.char_description = '覆盖的角色描述'; 将会覆盖角色描述。具体见Overrides 参数详情

injects? ​

max_chat_history? ​

  • 类型: 'all'|number
  • 描述: 最多使用多少条聊天历史

返回值 ​

  • 生成的最终文本: string

示例 ​

typescript
const result = await generate({ user_input: "你好", should_stream: true });
typescript
const result = await generate({
  user_input: "你好",
  image: "https://example.com/image.jpg",
});
typescript
const result = await generate({
  user_input: '你好',
  injects: [{ role: 'system', content: '思维链...', position: 'in_chat', depth: 0, should_scan: true, }]
  overrides: {
    char_personality: '温柔',
    world_info_before: '',
    chat_history: {
      prompts: [],
    }
  }
});

generateRaw ​

不使用 SillyTavern 当前启用的预设，让 AI 生成一段文本。

typescript
function generateRaw(config: GenerateConfig): Promise<string>;
typescript
type GenerateRawConfig = {
  /**
   * 用户输入.
   *
   * 如果设置, 则无论 ordered_prompts 中是否有 'user_input' 都会加入该用户输入提示词; 默认加入在 'chat_history' 末尾.
   */
  user_input?: string;

  /**
   * 图片输入，支持以下格式：
   * - File 对象：通过 input[type="file"] 获取的文件对象
   * - Base64 字符串：图片的 base64 编码
   * - URL 字符串：图片的在线地址
   */
  image?: File | string | (File | string)[];

  /**
   * 是否启用流式传输; 默认为 `false`.
   *
   * 若启用流式传输, 每次得到流式传输结果时, 函数将会发送事件:
   * - `ifraem_events.STREAM_TOKEN_RECEIVED_FULLY`: 监听它可以得到流式传输的当前完整文本 ("这是", "这是一条", "这是一条流式传输")
   * - `iframe_events.STREAM_TOKEN_RECEIVED_INCREMENTALLY`: 监听它可以得到流式传输的当前增量文本 ("这是", "一条", "流式传输")
   *
   * @example
   * eventOn(iframe_events.STREAM_TOKEN_RECEIVED_FULLY, text => console.info(text));
   */
  should_stream?: boolean;

  /**
   * 覆盖选项. 若设置, 则 `overrides` 中给出的字段将会覆盖对应的提示词.
   *   如 `overrides.char_description = '覆盖的角色描述';` 将会覆盖提示词
   */
  overrides?: Overrides;

  injects?: Omit<InjectionPrompt, 'id'>[];

  /**
   * 一个提示词数组, 数组元素将会按顺序发给 ai, 因而相当于自定义预设. 该数组允许存放两种类型:
   * - `BuiltinPrompt`: 内置提示词. 由于不使用预设, 如果需要 "角色描述" 等提示词, 你需要自己指定要用哪些并给出顺序
   *                      如果不想自己指定, 可通过 `builtin_prompt_default_order` 得到酒馆默认预设所使用的顺序 (但对于这种情况, 也许你更应该用 `generate`).
   * - `RolePrompt`: 要额外给定的提示词.
   */
  ordered_prompts?: (BuiltinPrompt | RolePrompt)[];

  /** 最多使用多少条聊天历史; 默认为 'all' */
  max_chat_history?: 'all' | number;

  /** 自定义API配置 */
  custom_api?: CustomApiConfig;

  /**
   * 唯一id
   *
   * 可以并发生成，并可以通过stopGenerateById停止特定生成，不设置默认生成uuid，在发送的事件中也会返回该id
   */
  generation_id?: string;
};

参数 ​

generation_id? ​

  • 类型: string
  • 描述: 生成 ID。如果设置，可以通过事件监听接收某一特定请求的生成结果。以及中止特定id的请求。具体见函数的事件发送，不提供时，则使用随机uuid作为id。

user_input? ​

  • 类型: string
  • 描述: 如果设置，则无论 ordered_prompts 中是否有 user_input 都会加入该用户输入提示词；默认加入在 chat_history 末尾。

should_stream? ​

  • 类型: boolean
  • 描述: 是否启用流式传输；默认为 false

image? ​

  • 类型: File|string[]

  • 描述: 图片输入，支持以数组形式输入多张图片：

    • File 对象：通过 input[type="file"] 获取的文件对象
    • Base64 字符串：图片的 base64 编码
    • URL 字符串：图片的在线地址

custom_api? ​

overrides? ​

  • 类型: Overrides
  • 描述: 覆盖选项。若设置, 则 overrides 中给出的字段将会覆盖对应的提示词。如 overrides.char_description = '覆盖的角色描述'; 将会覆盖角色描述。具体见Overrides 参数详情

injects? ​

max_chat_history? ​

  • 类型: 'all'|number
  • 描述: 最多使用多少条聊天历史

ordered_prompts? ​

  • 类型: (BuiltinPrompt | RolePrompt)[]
  • 描述: 一个提示词数组，数组元素将会按顺序发给 ai，因而相当于自定义预设。该数组允许存放两种类型：
    • BuiltinPrompt: 内置提示词。由于不使用预设, 如果需要 "角色描述" 等提示词, 你需要自己指定需要使用哪些并给出顺序。如果不想自己指定, 函数会自行使用 builtin_prompt_default_order 中的酒馆默认预设顺序（但对于这种情况，你也许更应该用 generate）。
    • RolePrompt: 要额外给定的提示词。

返回值 ​

  • 生成的最终文本: string

示例 ​

typescript
// 自定义内置提示词顺序, 未在 ordered_prompts 中给出的将不会被使用
const result = await generateRaw({
  user_input: "你好",
  ordered_prompts: [
    "char_description",
    { role: "system", content: "系统提示" },
    "chat_history",
    "user_input",
  ],
});

通过事件获取生成结果 ​

函数的事件发送 ​

该函数在执行过程中将会发送以下事件:

  • iframe_events.GENERATION_STARTED：生成开始
  • 若启用流式传输, iframe_events.STREAM_TOKEN_RECEIVED_FULLY：监听它可以得到流式传输的当前完整文本 ("这是", "这是一条", "这是一条流式传输")
  • 若启用流式传输, iframe_events.STREAM_TOKEN_RECEIVED_INCREMENTALLY：监听它可以得到流式传输的当前增量文本 ("这是", "一条", "流式传输")
  • iframe_events.GENERATION_ENDED：生成结束, 监听它可以得到生成的最终文本 (当然也能通过函数返回值获得)
  • 生成时将一同发送generation_id
typescript
  [iframe_events.GENERATION_STARTED]: (generation_id: string) => void;
  [iframe_events.STREAM_TOKEN_RECEIVED_FULLY]: (full_text: string, generation_id: string) => void;
  [iframe_events.STREAM_TOKEN_RECEIVED_INCREMENTALLY]: (incremental_text: string, generation_id: string) => void;
  [iframe_events.GENERATION_ENDED]: (text: string, generation_id: string) => void;

示例 ​

参数详情 ​

Overrides ​

world_info_before? ​

  • 类型: string
  • 描述: 世界书(角色定义前)

persona_description? ​

  • 类型: string
  • 描述: 用户描述

char_description? ​

  • 类型: string
  • 描述: 角色描述

char_personality? ​

  • 类型: string
  • 描述: 角色性格

scenario? ​

  • 类型: string
  • 描述: 场景

world_info_after? ​

  • 类型: string
  • 描述: 世界书(角色定义后)

dialogue_examples? ​

  • 类型: string
  • 描述: 对话示例

chat_history? ​

  • 类型: {with_depth_entries?: boolean, author_note?: string; prompts?: RolePrompt[];}
  • 描述: 聊天历史，其中
    • with_depth_entries: 是否启用世界书中按深度插入的条目; 默认为 true
    • author_note: 若设置, 覆盖 "作者注释" 为给定的字符串
    • prompts: 若设置, 覆盖 "聊天历史" 为给定的提示词，详见RolePrompt 格式

RolePrompt ​

role ​

  • 类型: 'system' | 'assistant' | 'user'
  • 描述: 角色

content ​

  • 类型: string
  • 描述: 提示词内容

BuiltinPrompt ​

不指定 ordered_prompts 时，将使用以下默认顺序排列提示词：

typescript
const builtin_prompt_default_order: BuiltinPrompt[] = [
  "world_info_before", // 世界书(角色定义前)
  "persona_description", // 用户描述
  "char_description", // 角色描述
  "char_personality", // 角色性格
  "scenario", // 场景
  "world_info_after", // 世界书(角色定义后)
  "dialogue_examples", // 对话示例
  "chat_history", // 聊天历史 (含世界书中按深度插入的条目、作者注释)
  "user_input", // 用户输入
];

仅以下字符串可被 generateRaw 识别：

typescript
type BuiltinPrompt =
  | "world_info_before" // 世界书(角色定义前)
  | "persona_description" // 用户描述
  | "char_description" // 角色描述
  | "char_personality" // 角色性格
  | "scenario" // 场景
  | "world_info_after" // 世界书(角色定义后)
  | "dialogue_examples" // 对话示例
  | "chat_history" // 聊天历史 (含世界书中按深度插入的条目、作者注释)
  | "user_input"; // 用户输入

user_input与chat_history的关系：

在generateRaw中，user_input可以自由选择放置的位置了。关于user_input和chat_history的关系如下：

当chat_history不在ordered_prompts：

  • 如果user_input未在 ordered_prompts 中：将自动添加到所有提示词的最后面
  • 如果user_input在 ordered_prompts 中：以user_input在 ordered_prompts 中的位置为准

当chat_history在ordered_prompts时：

  • 如果user_input未在 ordered_prompts 中：将自动插入到最新一条聊天记录后
  • 如果user_input在 ordered_prompts 中：user_input和chat_history会分别插入到 ordered_prompts 中指示的位置

CustomApiConfig ​

apiurl? ​

  • 类型: string
  • 描述: 自定义 API 地址

key? ​

  • 类型: string
  • 描述: API 密钥

model? ​

  • 类型: string
  • 描述: 模型名称

source? ​

  • 类型: string
  • 描述: API 源，默认为 'openai'

注意

source 参数用于指定 API 源，目前支持的源请查看酒馆官方代码SillyTavern/src/constants.js（可点击跳转）所列出的源。 但由于是通过强制使用反代来做到自定义 API，所以可能不支持在酒馆中未提供反向代理选项的聊天补全来源，但主流的openai、claude、makersuite(gemini)、deepseek都支持。

作者：KAKAA, 青空莉想做舞台少女的狗

© Copyright 2025, N0VI028.
Licensed under Aladdin, Icons by Icons8