> ## 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.

# configurações de sessão ai_function_*

> Configurações de sessão do ClickHouse no grupo ai_function_* gerado.

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>Recurso beta</span>
        </a>;
};

export const VersionHistory = ({rows = []}) => {
  if (rows.length === 0) {
    return null;
  }
  const headers = ["Versão", "Valor padrão", "Comentário"];
  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
  }}>
        Histórico de versões
      </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
  }}>Tipo</div>
      <div style={{
    overflowWrap: "anywhere"
  }}>{type}</div>
      <div style={{
    fontWeight: 600,
    opacity: 0.72,
    marginInlineStart: "0.5rem"
  }}>Padrão</div>
      <div style={{
    overflowWrap: "anywhere"
  }}>{default_value}</div>
      {changeable_without_restart && <div style={{
    fontWeight: 600,
    opacity: 0.72,
    marginInlineStart: "0.5rem"
  }}>
          Pode ser alterado sem reiniciar
        </div>}
      {changeable_without_restart && <div style={{
    overflowWrap: "anywhere"
  }}>
          {changeable_without_restart}
        </div>}
    </div>;
};

Essas configurações estão disponíveis em [system.settings](/pt-BR/reference/system-tables/settings) e são autogeradas a partir do [código-fonte](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": "As funções de IA agora rejeitam, por padrão, endpoints (http) inseguros em hosts remotos."}]}]} />

Se false (padrão), as funções de IA se recusam a usar um `endpoint` de coleção nomeada que enviaria prompts e chaves de API por uma conexão não criptografada a um host remoto: qualquer endpoint não HTTPS cujo host não seja de loopback é rejeitado com uma exceção. Endpoints de loopback (por exemplo, um servidor de modelo local em `http://localhost`) são sempre permitidos. Defina como true para permitir endpoints `http://` em texto simples em hosts remotos.

## ai\_function\_embedding\_default\_credentials

<BetaBadge />

<VersionHistory rows={[{"id": "row-1","items": [{"label": "26.8"},{"label": ""},{"label": "Nova configuração"}]}]} />

Nome da coleção nomeada usada pelas funções de embedding (`aiEmbed`, `aiSimilarity`) quando a chamada não fornece `credentials` no mapa de parâmetros. Vazio significa que não há valor padrão: essas chamadas devem fornecer `credentials` explicitamente. Essas funções usam `model` como argumento posicional obrigatório, e não a partir da coleção nomeada. Isso é mantido separado de `ai_function_text_default_credentials` porque um endpoint de embeddings é diferente de um endpoint de chat.

## 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": "Nova configuração"}]}]} />

Número máximo de textos a serem incluídos em uma única requisição HTTP feita pelas funções de embedding (`aiEmbed`, `aiSimilarity`). Os textos são agrupados em lotes desse tamanho para reduzir a sobrecarga das chamadas de API. Por exemplo, 500 textos únicos com lote de 100 resultam em 5 requisições 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": "Por padrão, limita as chamadas HTTP de saída da função de IA por consulta (anteriormente 0 — ilimitadas)."}]}, {"id": "row-2","items": [{"label": "26.4"},{"label": "0"},{"label": "Nova configuração"}]}]} />

Número máximo de requisições HTTP que as funções de IA podem encaminhar em uma consulta. Aplicado independentemente por cada servidor e fragmento de consulta: em um contexto de execução, é um limite exato compartilhado por todas as funções de IA, blocos e threads nele, mas uma consulta distribuída (entre shards ou fragmentos de réplicas paralelas) pode encaminhar até esse número de requisições por shard/fragmento. Deve ser definido na consulta de nível superior — uma substituição de `SETTINGS` em uma subconsulta é ignorada. Defina como 0 para desabilitar.

## 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": "Nova configuração"}]}]} />

Número máximo total de tokens de entrada (`prompt`) em todas as chamadas de API da função de IA em uma única consulta. O total é contabilizado de forma cumulativa com base nas respostas dos provedores. Observe que esse limite pode ser excedido pelo volume de tokens de entrada de até uma chamada por solicitação em andamento, já que os tokens de entrada de uma chamada não são conhecidos até que sua resposta chegue. Assim como as outras cotas de IA, ele é aplicado por servidor / fragmento de consulta, não sendo somado em uma consulta distribuída, e deve ser definido na consulta de nível superior — uma substituição de `SETTINGS` em uma subconsulta é ignorada. Defina como 0 para desativar.

Esse limite só é aplicado a provedores que informam um objeto `usage` na resposta (OpenAI, Anthropic, vLLM). Provedores que omitem o uso de tokens (principalmente o HuggingFace TEI) fazem com que o contador permaneça em 0 — use `ai_function_max_api_calls_per_query` para limitar essas chamadas.

## 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": "Nova configuração"}]}]} />

Máximo total de tokens de saída (completion) em todas as chamadas de API da função de IA em uma única consulta. O rastreamento é cumulativo com base nas respostas do provedor. Observe que esse limite pode ser excedido em até o volume de tokens de saída de uma chamada por solicitação em andamento, já que os tokens de saída de uma chamada não são conhecidos até a chegada da resposta. Assim como as outras cotas de IA, ele é aplicado por servidor / fragmento de consulta, não sendo somado em uma consulta distribuída, e deve ser definido na consulta de nível superior — uma substituição de `SETTINGS` em uma subconsulta é ignorada. Defina como 0 para desativar.

Esse limite só é aplicado a provedores que informam um objeto `usage` na resposta (OpenAI, Anthropic, vLLM). Ele não se aplica às funções de embedding (`aiEmbed`, `aiSimilarity`), que nunca produzem tokens de saída.

## ai\_function\_max\_retries

<BetaBadge />

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

<VersionHistory rows={[{"id": "row-1","items": [{"label": "26.9"},{"label": "1"},{"label": "Por padrão, tenta novamente uma vez em caso de erro transitório da API, para que um único 429 ou 5xx do provedor não faça a consulta falhar."}]}, {"id": "row-2","items": [{"label": "26.4"},{"label": "0"},{"label": "Nova configuração"}]}]} />

Número máximo de retentativas para erros transitórios por solicitação individual à API. Cada retentativa usa backoff exponencial a partir de `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": "Nova configuração"}]}]} />

Timeout em segundos para requisições HTTP individuais feitas por funções de IA (chat completions com IA e chamadas à API de embedding). Se uma requisição não for concluída dentro desse tempo, ela será considerada malsucedida e poderá ser repetida de acordo com `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": "Nova configuração"}]}]} />

Atraso inicial, em milissegundos, antes da primeira retentativa de uma solicitação de API com falha da função de IA. O atraso dobra a cada tentativa subsequente (backoff exponencial). Por exemplo, com as configurações padrão: 1000ms, 2000ms, 4000ms.

## ai\_function\_text\_default\_credentials

<BetaBadge />

<VersionHistory rows={[{"id": "row-1","items": [{"label": "26.8"},{"label": ""},{"label": "Nova configuração"}]}]} />

Nome da coleção nomeada usada pelas funções de IA de texto (`aiGenerate`, `aiClassify`, `aiFilter`, `aiExtract`, `aiTranslate`, `aiRedact`) quando a chamada não fornece `credentials` no mapa de parâmetros. Vazio significa que não há padrão: essas chamadas devem fornecer `credentials` explicitamente. Um endpoint de chat completions é diferente de um de embeddings, portanto isso é separado de `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": "Nova configuração"}]}]} />

Se true (padrão), uma chamada de função de IA que falhar permanentemente após esgotar todas as tentativas interrompe a consulta com uma exceção. Se false, a linha com falha recebe o valor padrão para o tipo da coluna (string vazia para String), e o processamento continua.

## 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": "Nova configuração"}]}]} />

Se true (padrão), exceder um limite de cota de uma função de IA (`ai_function_max_input_tokens_per_query`, `ai_function_max_output_tokens_per_query` ou `ai_function_max_api_calls_per_query`) interrompe a consulta com uma exceção. Se false, as linhas restantes recebem o valor padrão do tipo de coluna (string vazia para String). Assim como os limites de cota, isso deve ser definido na consulta de nível superior — uma substituição de `SETTINGS` em uma subconsulta é ignorada.