> ## Documentation Index
> Fetch the complete documentation index at: https://clickhouse.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# ai_function_* 会话设置

> ClickHouse 中 ai_function_* 生成组的会话设置。

export const SettingsInfoBlock = ({type, default_value, changeable_without_restart}) => {
  return <div className="not-prose" style={{
    display: "flex",
    flexWrap: "wrap",
    alignItems: "baseline",
    columnGap: "0.5rem",
    rowGap: "0.125rem",
    margin: "0.375rem 0",
    fontSize: "0.8125rem",
    lineHeight: "1.125rem"
  }}>
      <div style={{
    fontWeight: 600,
    opacity: 0.72
  }}>类型</div>
      <div style={{
    overflowWrap: "anywhere"
  }}>{type}</div>
      <div style={{
    fontWeight: 600,
    opacity: 0.72,
    marginInlineStart: "0.5rem"
  }}>默认值</div>
      <div style={{
    overflowWrap: "anywhere"
  }}>{default_value}</div>
      {changeable_without_restart && <div style={{
    fontWeight: 600,
    opacity: 0.72,
    marginInlineStart: "0.5rem"
  }}>
          无需重启即可更改
        </div>}
      {changeable_without_restart && <div style={{
    overflowWrap: "anywhere"
  }}>
          {changeable_without_restart}
        </div>}
    </div>;
};

export const ExperimentalBadge = () => {
  return <div className="experimentalBadge">
            <div className="experimentalIcon">
            <svg width="16" height="16" viewBox="0 0 16 16" fill="none" xmlns="http://www.w3.org/2000/svg">
                <path strokeWidth="1.25" d="M5.5 2H10.5" stroke="currentColor" strokeLinecap="round" strokeLinejoin="round" />
                <path strokeWidth="1.25" d="M9.50015 2V6.19625L13.4283 12.7425C13.4738 12.8183 13.4985 12.9049 13.4996 12.9934C13.5008 13.0818 13.4785 13.169 13.435 13.246C13.3914 13.323 13.3283 13.3871 13.2519 13.4317C13.1755 13.4764 13.0886 13.4999 13.0002 13.5H3.00015C2.91164 13.5 2.8247 13.4766 2.74822 13.432C2.67174 13.3874 2.60847 13.3233 2.56487 13.2463C2.52126 13.1693 2.49889 13.082 2.50004 12.9935C2.50119 12.905 2.52582 12.8184 2.5714 12.7425L6.50015 6.19625V2" stroke="currentColor" strokeLinecap="round" strokeLinejoin="round" />
                <path strokeWidth="1.25" d="M4.47656 9.56754C5.30344 9.41254 6.47656 9.47942 7.99969 10.25C10.0153 11.2707 11.4216 11.0569 12.2184 10.7282" stroke="currentColor" strokeLinecap="round" strokeLinejoin="round" />
            </svg>
        </div>
            Experimental 功能。 <u><a href="/docs/docs/beta-and-experimental-features#experimental-features">了解详情。</a></u>
        </div>;
};

这些设置可在 [system.settings](/docs/zh/reference/system-tables/settings) 中查看，且由 [源代码](https://github.com/ClickHouse/ClickHouse/blob/master/src/Core/Settings.cpp) 自动生成。

<div id="ai_function_embedding_default_credentials">
  ## ai\_function\_embedding\_default\_credentials
</div>

<ExperimentalBadge />

<VersionHistory rows={[{"id": "row-1","items": [{"label": "26.7"},{"label": ""},{"label": "新增设置"}]}]} />

当调用未在其参数映射中传递 `credentials` 时，`aiEmbed` 使用的命名集合名称。留空表示没有默认值：此类调用必须显式传递 `credentials`。`aiEmbed` 将 `model` 作为必需的位置参数传入，而不是从命名集合中获取。之所以与 `ai_function_text_default_credentials` 分开，是因为嵌入向量端点与聊天端点不同。

<div id="ai_function_embedding_max_batch_size">
  ## ai\_function\_embedding\_max\_batch\_size
</div>

<ExperimentalBadge />

<SettingsInfoBlock type="NonZeroUInt64" default_value="100" />

<VersionHistory rows={[{"id": "row-1","items": [{"label": "26.6"},{"label": "100"},{"label": "新增设置"}]}]} />

单个由 `aiEmbed` 发起的 HTTP 请求中最多可包含的文本数量。文本会按该大小分成批次，以减少 API 调用开销。例如，500 条唯一文本在批次大小为 100 时，会产生 5 个 HTTP 请求。

<div id="ai_function_max_api_calls_per_query">
  ## ai\_function\_max\_api\_calls\_per\_query
</div>

<ExperimentalBadge />

<SettingsInfoBlock type="UInt64" default_value="0" />

<VersionHistory rows={[{"id": "row-1","items": [{"label": "26.4"},{"label": "0"},{"label": "新增设置"}]}]} />

每次查询中，AI 函数可发起的 HTTP 请求最大数量。设置为 0 可禁用。

<div id="ai_function_max_input_tokens_per_query">
  ## ai\_function\_max\_input\_tokens\_per\_query
</div>

<ExperimentalBadge />

<SettingsInfoBlock type="UInt64" default_value="1000000" />

<VersionHistory rows={[{"id": "row-1","items": [{"label": "26.4"},{"label": "1000000"},{"label": "新增设置"}]}]} />

单个查询中，所有 AI 函数 API 调用的输入 (prompt) 标记总数上限。该值根据提供商响应累计统计。请注意，由于单次调用的输入标记数事先无法得知，因此该限制可能会被超出一次调用对应的输入标记数。设为 0 可禁用。

此限制仅对在响应中返回 `usage` 对象的提供商生效 (OpenAI、Anthropic、vLLM) 。如果提供商未返回标记使用量 (尤其是 HuggingFace TEI) ，计数器将保持为 0——请改用 `ai_function_max_api_calls_per_query` 来限制此类调用。

<div id="ai_function_max_output_tokens_per_query">
  ## ai\_function\_max\_output\_tokens\_per\_query
</div>

<ExperimentalBadge />

<SettingsInfoBlock type="UInt64" default_value="500000" />

<VersionHistory rows={[{"id": "row-1","items": [{"label": "26.4"},{"label": "500000"},{"label": "新增设置"}]}]} />

单个查询中，所有 AI 函数 API 调用产生的输出 (completion) 标记总数上限。该值会根据提供商响应中的数据进行累计统计。请注意，由于单次调用的输出标记数无法预先得知，因此实际输出可能会超出该限制一个调用的输出量。设置为 0 可禁用此限制。

此限制仅对在响应中返回 `usage` 对象的提供商生效 (OpenAI、Anthropic、vLLM) 。它不适用于 embedding 函数 (尤其是 aiEmbed) ，因为这类函数不会产生输出标记。

<div id="ai_function_max_retries">
  ## ai\_function\_max\_retries
</div>

<ExperimentalBadge />

<SettingsInfoBlock type="UInt64" default_value="0" />

<VersionHistory rows={[{"id": "row-1","items": [{"label": "26.4"},{"label": "0"},{"label": "新增设置"}]}]} />

单个 API 请求在出现瞬时错误时的最大重试次数。每次重试都会采用指数退避，初始延迟由 `ai_function_retry_initial_delay_ms` 指定。

<div id="ai_function_request_timeout_sec">
  ## ai\_function\_request\_timeout\_sec
</div>

<ExperimentalBadge />

<SettingsInfoBlock type="UInt64" default_value="60" />

<VersionHistory rows={[{"id": "row-1","items": [{"label": "26.4"},{"label": "60"},{"label": "新增设置"}]}]} />

AI 函数发起的单个 HTTP 请求 (AI 聊天补全和 embedding API 调用) 的超时时间，单位为秒。如果请求未在此时间内完成，则会被视为失败，并可根据 `ai_function_max_retries` 进行重试。

<div id="ai_function_retry_initial_delay_ms">
  ## ai\_function\_retry\_initial\_delay\_ms
</div>

<ExperimentalBadge />

<SettingsInfoBlock type="UInt64" default_value="1000" />

<VersionHistory rows={[{"id": "row-1","items": [{"label": "26.4"},{"label": "1000"},{"label": "新增设置"}]}]} />

失败的 AI 函数 API 请求在首次重试前的初始延迟，单位为毫秒。之后每次重试时，延迟都会翻倍 (指数退避) 。例如，在默认设置下：1000ms、2000ms、4000ms。

<div id="ai_function_text_default_credentials">
  ## ai\_function\_text\_default\_credentials
</div>

<ExperimentalBadge />

<VersionHistory rows={[{"id": "row-1","items": [{"label": "26.7"},{"label": ""},{"label": "新增设置"}]}]} />

当调用未在参数映射中传递 `credentials` 时，文本 AI 函数 (`aiGenerate`、`aiClassify`、`aiExtract`、`aiTranslate`) 将使用此命名集合的名称。为空表示没有默认值：此类调用必须显式传递 `credentials`。聊天补全端点与嵌入向量端点不同，因此该设置与 `ai_function_embedding_default_credentials` 分开。

<div id="ai_function_throw_on_error">
  ## ai\_function\_throw\_on\_error
</div>

<ExperimentalBadge />

<SettingsInfoBlock type="Bool" default_value="1" />

<VersionHistory rows={[{"id": "row-1","items": [{"label": "26.4"},{"label": "1"},{"label": "新增设置"}]}]} />

如果为 true (默认值) ，AI 函数调用在耗尽所有重试后仍永久失败时，会抛出异常并中止查询。如果为 false，失败的行会被赋予该列类型的默认值 (String 的默认值为空字符串) ，并继续处理。

<div id="ai_function_throw_on_quota_exceeded">
  ## ai\_function\_throw\_on\_quota\_exceeded
</div>

<ExperimentalBadge />

<SettingsInfoBlock type="Bool" default_value="1" />

<VersionHistory rows={[{"id": "row-1","items": [{"label": "26.4"},{"label": "1"},{"label": "新增设置"}]}]} />

如果为 true (默认值) ，当超出 AI 函数配额限制 (`ai_function_max_input_tokens_per_query`、`ai_function_max_output_tokens_per_query` 或 `ai_function_max_api_calls_per_query`) 时，查询会因抛出异常而中止。如果为 false，剩余行将接收该列类型的默认值 (String 的默认值为空字符串) 。