请求生成

提示

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

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

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

注意

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

generate

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

generateGenerateConfig

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

type GenerateConfig = {
  /**
   * 请求生成的唯一标识符, 不设置则默认生成一个随机标识符.
   *
   * 当有多个 generate/generateRaw 同时请求生成时, 可以为每个请求指定唯一标识符, 从而能用 `stopGenerationById` 停止特定生成请求, 或正确监听对应的生成事件.
   */
  generation_id?: string;

  /** 用户输入 */
  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;

  /**
   * 是否静默生成; 默认为 `false`.
   * - `false`: 酒馆页面的发送按钮将会变为停止按钮, 点击停止按钮会中断所有非静默生成请求
   * - `true`: 不影响酒馆停止按钮状态, 点击停止按钮不会中断该生成
   *
   * 虽然静默生成不能通过停止按钮中断, 但可以在代码中使用以下方式停止生成:
   * - 使用该生成请求的 `generation_id` 调用 `stopGenerationById`
   * - 调用 `stopAllGeneration`
   */
  should_silence?: boolean;

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

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

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

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

/**
 * 预设为内置提示词设置的默认顺序
 */
declare const builtin_prompt_default_order: BuiltinPrompt[];

type BuiltinPrompt =
  | 'world_info_before'
  | 'persona_description'
  | 'char_description'
  | 'char_personality'
  | 'scenario'
  | 'world_info_after'
  | 'dialogue_examples'
  | 'chat_history'
  | 'user_input';

type RolePrompt = {
  role: 'system' | 'assistant' | 'user';
  content: string;
  image?: File | string | (File | string)[];
};

type Overrides = {
  world_info_before?: string;
  persona_description?: string;
  char_description?: string;
  char_personality?: string;
  scenario?: string;
  world_info_after?: string;
  dialogue_examples?: string;

  /**
   * 聊天历史
   * - `with_depth_entries`: 是否启用世界书中按深度插入的条目; 默认为 `true`
   * - `author_note`: 若设置, 覆盖 "作者注释" 为给定的字符串
   * - `prompts`: 若设置, 覆盖 "聊天历史" 为给定的提示词
   */
  chat_history?: {
    with_depth_entries?: boolean;
    author_note?: string;
    prompts?: RolePrompt[];
  };
};

/**
 * 自定义API配置
 */
type CustomApiConfig = {
  /** 自定义API地址 */
  apiurl: string;
  /** API密钥 */
  key?: string;
  /** 模型名称 */
  model: string;
  /** API源，默认为 'openai' */
  source?: string;

  /** 最大回复 tokens 度 */
  max_tokens?: 'same_as_preset' | 'unset' | number;
  /** 温度 */
  temperature?: 'same_as_preset' | 'unset' | number;
  /** 频率惩罚 */
  frequency_penalty?: 'same_as_preset' | 'unset' | number;
  /** 存在惩罚 */
  presence_penalty?: 'same_as_preset' | 'unset' | number;
  top_p?: 'same_as_preset' | 'unset' | number;
  top_k?: 'same_as_preset' | 'unset' | number;
};

参数

`generation_id?`

类型: string
描述: 请求生成的唯一标识符, 不设置则默认生成一个随机标识符. 当有多个 generate/generateRaw 同时请求生成时, 可以为每个请求指定唯一标识符, 从而能用 stopGenerationById 停止特定生成请求, 或正确监听对应的生成事件.

`user_input?`

类型: string
描述: 用户输入

`should_stream?`

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

`should_silence?`

类型: boolean
描述: 是否静默生成; 默认为 false. 静默生成不会影响酒馆停止按钮状态, 点击停止按钮不会中断该生成. 具体见GenerateConfig 参数详情

`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: "你好" });
console.info('收到回复: ', result);

const result = await generate({
  user_input: "你好",
  image: "https://example.com/image.jpg",
});
console.info('收到回复: ', result);

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: [],
    }
  }
});
console.info('收到回复: ', result);

// 需要预先监听事件来接收流式回复
eventOn(iframe_events.STREAM_TOKEN_RECEIVED_FULLY, text => {
  console.info('收到流式回复: ', text);
});

// 然后进行生成
const result = await generate({ user_input: '你好', should_stream: true });
console.info('收到最终回复: ', result);

generateRaw

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

generateRawGenerateConfig

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

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

参数

与 `generate` 共用参数

所有 generate 支持的参数, 在这里也能使用

`ordered_prompts?`

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

`user_input` 与 `chat_history` 的关系

在 generateRaw中, user_input 可以自由选择放置的位置了.

关于 user_input 和 chat_history 的关系如下:

当 ordered_prompts 中没有设置 chat_history:

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

当 ordered_prompts 中设置了 chat_history:

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

返回值

生成的最终文本: string

示例

自定义内置提示词顺序使用自定义API和自定义提示词顺序

const result = await generateRaw({
  user_input: "你好",
  // 未在 ordered_prompts 中给出的将不会被使用
  ordered_prompts: [
    "char_description",
    { role: "system", content: "系统提示" },
    "chat_history",
    "user_input",
  ],
});
console.info('收到回复: ', result);

const result = await generateRaw({
  user_input: '你好',
  custom_api: {
    apiurl: 'https://your-proxy-url.com',
    key: 'your-api-key',
    model: 'gpt-4',
    source: 'openai'
  },
  ordered_prompts: [
    'char_description',
    'chat_history',
    'user_input',
  ]
})
console.info('收到回复: ', result);

通过事件获取生成结果

函数的事件发送

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

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;

示例

// 需要预先监听事件来接收流式回复
eventOn(iframe_events.STREAM_TOKEN_RECEIVED_FULLY, text => {
  console.info('收到流式回复: ', text);
});

// 然后进行生成
const result = await generate({ user_input: '你好', should_stream: true });
console.info('收到最终回复: ', result);

getModelList

获取模型列表

getModelList

function getModelList(custom_api: { apiurl: string; key?: string }): Promise<string[]>;

参数

`apiurl`

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

`key`

类型: string
描述: 自定义 API 密钥

返回值

模型列表: string[]

异常

当获取模型失败时, 会抛出异常

stopGenerationById

根据生成请求唯一标识符停止特定的生成请求.

stopGenerationById

function stopGenerationById(generationId: string): Promise<boolean>

参数

`generation_id`

类型: string
描述: 生成请求唯一标识符, 用于标识要停止的生成请求

返回值

类型: Promise<boolean>
描述: 是否成功停止生成

stopAllGeneration

停止所有正在进行的生成请求.

stopAllGeneration

function stopAllGeneration(): Promise<boolean>;

返回值

类型: Promise<boolean>
描述: 是否成功停止所有生成

请求生成 ​

generate ​

参数 ​

generation_id? ​

user_input? ​

should_stream? ​

should_silence? ​

image? ​

custom_api? ​

overrides? ​

injects? ​

max_chat_history? ​

返回值 ​

示例 ​

generateRaw ​

参数 ​

与 generate 共用参数 ​

ordered_prompts? ​

user_input 与 chat_history 的关系 ​

返回值 ​

示例 ​

通过事件获取生成结果 ​

函数的事件发送 ​

示例 ​

getModelList ​

参数 ​

apiurl ​

key ​

返回值 ​

异常 ​

stopGenerationById ​

参数 ​

generation_id ​

返回值 ​

stopAllGeneration ​

返回值 ​

请求生成

generate

参数

`generation_id?`

`user_input?`

`should_stream?`

`should_silence?`

`image?`

`custom_api?`

`overrides?`

`injects?`

`max_chat_history?`

返回值

示例

generateRaw

参数

与 `generate` 共用参数

`ordered_prompts?`

`user_input` 与 `chat_history` 的关系

返回值

示例

通过事件获取生成结果

函数的事件发送

示例

getModelList

参数

`apiurl`

`key`

返回值

异常

stopGenerationById

参数

`generation_id`

返回值

stopAllGeneration

返回值