请求生成

提示

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

酒馆助手提供了函数用于更加灵活地请求 AI 生成回复, 你可以通过它来自定义生成时要采用的提示词配置.

点击查看对应类型定义文件 (可发给 AI 或 IDE 使用, 酒馆助手界面中提供了打包下载)

注意

目前仅支持聊天补全 (Chat Completion).

generate

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

generateGenerateConfig

function generate(config: GenerateConfig): Promise<string>;

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 请求的生成结果, 或中止特定 id 的请求, 具体见函数的事件发送. 不提供时, 则使用随机 uuid 作为 id

`user_input?`

类型: string
描述: 用户输入

`should_stream?`

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

`image?`

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

`custom_api?`

类型: CustomApiConfig
描述: 自定义 API 配置, 具体见CustomApiConfig 参数详情

`overrides?`

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

`injects?`

类型: Omit<InjectionPrompt, 'id'>[]
描述: 要额外注入的提示词, 具体见InjectionPrompt 参数详情

`max_chat_history?`

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

返回值

生成的最终文本: string

示例

流式生成图片输入注入、覆盖提示词

const result = await generate({ user_input: "你好", should_stream: true });

const result = await generate({
  user_input: "你好",
  image: "https://example.com/image.jpg",
});

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 生成一段文本

generateRawGenerateConfig

function generateRaw(config: GenerateConfig): Promise<string>;

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 请求的生成结果, 或中止特定 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?`

类型: CustomApiConfig
描述: 自定义 API 配置, 具体见CustomApiConfig 参数详情

`overrides?`

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

`injects?`

类型: Omit<InjectionPrompt, 'id'>[]
描述: 要额外注入的提示词, 具体见InjectionPrompt 参数详情

`max_chat_history?`

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

`ordered_prompts?`

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

返回值

生成的最终文本: string

示例

// 自定义内置提示词顺序, 未在 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

  [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 时, 将使用以下默认顺序排列提示词:

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 识别:

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'

`max_tokens?`

类型: number
描述: 最大回复 tokens 度

`temperature?`

类型: number
描述: 温度

`frequency_penalty?`

类型: number
描述: 频率惩罚

`presence_penalty?`

类型: number
描述: 存在惩罚

`top_p?`

类型: number
描述: top_p

注意

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

请求生成 ​

generate ​

参数 ​

generation_id? ​

user_input? ​

should_stream? ​

image? ​

custom_api? ​

overrides? ​

injects? ​

max_chat_history? ​

返回值 ​

示例 ​

generateRaw ​

参数 ​

generation_id? ​

user_input? ​

should_stream? ​

image? ​

custom_api? ​

overrides? ​

injects? ​

max_chat_history? ​

ordered_prompts? ​

返回值 ​

示例 ​

通过事件获取生成结果 ​

函数的事件发送 ​

示例 ​

参数详情 ​

Overrides ​

world_info_before? ​

persona_description? ​

char_description? ​

char_personality? ​

scenario? ​

world_info_after? ​

dialogue_examples? ​

chat_history? ​

RolePrompt ​

role ​

content ​

BuiltinPrompt ​

CustomApiConfig ​

apiurl? ​

key? ​

model ​

source? ​

max_tokens? ​

temperature? ​

frequency_penalty? ​

presence_penalty? ​

top_p? ​

请求生成

generate

参数

`generation_id?`

`user_input?`

`should_stream?`

`image?`

`custom_api?`

`overrides?`

`injects?`

`max_chat_history?`

返回值

示例

generateRaw

参数

`generation_id?`

`user_input?`

`should_stream?`

`image?`

`custom_api?`

`overrides?`

`injects?`

`max_chat_history?`

`ordered_prompts?`

返回值

示例

通过事件获取生成结果

函数的事件发送

示例

参数详情

`Overrides`

`world_info_before?`

`persona_description?`

`char_description?`

`char_personality?`

`scenario?`

`world_info_after?`

`dialogue_examples?`

`chat_history?`

`RolePrompt`

`role`

`content`

`BuiltinPrompt`

`CustomApiConfig`

`apiurl?`

`key?`

`model`

`source?`

`max_tokens?`

`temperature?`

`frequency_penalty?`

`presence_penalty?`

`top_p?`