> ## Documentation Index
> Fetch the complete documentation index at: https://private-7c7dfe99-parallel-read-in-order-multi-part.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# ai_function_* 会话设置

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

export const BetaBadge = ({link, galaxyTrack, galaxyEvent}) => {
  if (link) {
    return <a href={link} target="_blank" rel="noopener noreferrer" className="betaBadge" onClick={galaxyTrack && galaxyEvent ? galaxyOnClick(galaxyEvent) : undefined}>
                <span>Beta</span>
            </a>;
  }
  return <a href="https://clickhouse.com/docs/reference/settings/beta-and-experimental-features#beta-features" className="betaBadge">
            <span>Beta 版功能</span>
        </a>;
};

export const VersionHistory = ({rows = []}) => {
  if (rows.length === 0) {
    return null;
  }
  const headers = ["版本", "默认值", "注释"];
  const border = "1px solid rgba(128, 128, 128, 0.3)";
  const cell = {
    border,
    padding: "0.25rem 0.5rem",
    textAlign: "start",
    verticalAlign: "top"
  };
  return <details className="not-prose" style={{
    border,
    borderRadius: "0.5rem",
    margin: "0.5rem 0",
    padding: "0.5rem 0.75rem",
    fontSize: "0.8125rem",
    lineHeight: "1.125rem"
  }}>
      <summary style={{
    cursor: "pointer",
    fontWeight: 600,
    opacity: 0.72
  }}>
        版本历史
      </summary>
      <table style={{
    borderCollapse: "collapse",
    width: "100%",
    margin: "0.5rem 0 0"
  }}>
        <thead>
          <tr>
            {headers.map(header => <th key={header} style={{
    ...cell,
    fontWeight: 600,
    opacity: 0.72
  }}>
                {header}
              </th>)}
          </tr>
        </thead>
        <tbody>
          {rows.map((row, row_index) => <tr key={row.id ?? row_index}>
              {(row.items ?? []).map((item, item_index) => <td key={item_index} style={{
    ...cell,
    overflowWrap: "anywhere"
  }}>
                  {item?.label}
                </td>)}
            </tr>)}
        </tbody>
      </table>
    </details>;
};

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>;
};

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

## ai\_function\_allow\_insecure\_endpoint

<BetaBadge />

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

<VersionHistory rows={[{"id": "row-1","items": [{"label": "26.8"},{"label": "0"},{"label": "AI 函数现在默认拒绝使用指向远程主机的不安全（http）端点。"}]}]} />

如果为 false (默认值) ，AI 函数将拒绝使用命名集合中会通过未加密连接将提示词和 API 密钥发送到远程主机的 `endpoint`：所有主机不是回环地址的非 HTTPS 端点都会被拒绝，并引发异常。回环端点 (例如本地的 `http://localhost` 模型服务器) 始终允许。将其设置为 true，可允许远程主机上的明文 `http://` 端点。

## ai\_function\_embedding\_default\_credentials

<BetaBadge />

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

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

## ai\_function\_embedding\_max\_batch\_size

<BetaBadge />

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

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

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

## ai\_function\_max\_api\_calls\_per\_query

<BetaBadge />

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

<VersionHistory rows={[{"id": "row-1","items": [{"label": "26.8"},{"label": "1000"},{"label": "默认限制每次查询可发起的出站 AI 函数 HTTP 调用次数（此前为 0 - 不限制）。"}]}, {"id": "row-2","items": [{"label": "26.4"},{"label": "0"},{"label": "新增设置"}]}]} />

每次查询中，AI 函数可发起的 HTTP 请求最大数量。每台服务器和每个查询片段都会独立执行此限制：在单个执行上下文中，这是其中所有 AI 函数、块和线程共享的严格上限；但分布式查询 (跨 сегмент 或并行副本片段) 在每个 сегмент/片段中最多可发起这么多请求。必须在顶层查询中设置——子查询中的 `SETTINGS` 覆盖会被忽略。设置为 0 可禁用。

## ai\_function\_max\_input\_tokens\_per\_query

<BetaBadge />

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

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

单个查询中，所有 AI 函数 API 调用的输入 (提示词) 标记总数上限。该值根据提供商响应累计统计。请注意，由于在调用响应到达前无法得知其输入标记数，因此每个进行中的请求最多可能超出一次调用对应的输入标记数。与其他 AI 配额一样，此限制按每个服务器 / 查询片段执行，而不会在分布式查询中汇总，并且必须在顶层查询中设置——子查询中的 `SETTINGS` 覆盖将被忽略。设为 0 可禁用。

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

## ai\_function\_max\_output\_tokens\_per\_query

<BetaBadge />

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

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

单个查询中，所有 AI 函数 API 调用产生的输出 (补全) 标记总数上限。该值会根据提供商响应中的数据进行累计统计。请注意，由于在调用响应到达之前无法得知其输出标记数，因此每个进行中的请求实际输出可能会超出该限制最多一个调用的输出标记量。与其他 AI 配额一样，此限制按每个服务器 / 查询片段强制执行，不会跨分布式查询汇总，并且必须在顶层查询中设置——子查询的 `SETTINGS` 覆盖会被忽略。设置为 0 可禁用此限制。

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

## ai\_function\_max\_retries

<BetaBadge />

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

<VersionHistory rows={[{"id": "row-1","items": [{"label": "26.9"},{"label": "1"},{"label": "默认对暂时性 API 错误重试一次，因此提供商返回单个 429 或 5xx 不会导致查询失败。"}]}, {"id": "row-2","items": [{"label": "26.4"},{"label": "0"},{"label": "新增设置"}]}]} />

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

## ai\_function\_request\_timeout\_sec

<BetaBadge />

<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` 进行重试。

## ai\_function\_retry\_initial\_delay\_ms

<BetaBadge />

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

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

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

## ai\_function\_text\_default\_credentials

<BetaBadge />

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

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

## ai\_function\_throw\_on\_error

<BetaBadge />

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

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

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

## ai\_function\_throw\_on\_quota\_exceeded

<BetaBadge />

<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 的默认值为空字符串) 。与配额限制一样，必须在顶层查询中设置此项——子查询中的 `SETTINGS` 覆盖 将被忽略。