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

> Documentação sobre Funções de IA

# Funções de IA

Funções de IA são funções integradas do ClickHouse que você pode usar para chamar IA ou gerar embeddings para trabalhar com seus dados, extrair informações, classificar dados etc...

<Note>
  As funções de IA podem retornar saídas imprevisíveis. O resultado dependerá muito da qualidade do prompt e do modelo usado.
</Note>

Todas as funções compartilham uma infraestrutura comum que fornece:

* **Aplicação de cotas**: Limites por consulta para tokens ([`ai_function_max_input_tokens_per_query`](/pt-BR/reference/settings/session-settings#ai_function_max_input_tokens_per_query), [`ai_function_max_output_tokens_per_query`](/pt-BR/reference/settings/session-settings#ai_function_max_output_tokens_per_query)) e chamadas de API ([`ai_function_max_api_calls_per_query`](/pt-BR/reference/settings/session-settings#ai_function_max_api_calls_per_query)).
* **Retentativas com backoff**: Falhas transitórias são repetidas ([`ai_function_max_retries`](/pt-BR/reference/settings/session-settings#ai_function_max_retries)) com backoff exponencial ([`ai_function_retry_initial_delay_ms`](/pt-BR/reference/settings/session-settings#ai_function_retry_initial_delay_ms)).

<div id="configuration">
  ## Configuração
</div>

As funções de IA fazem referência a uma **coleção nomeada** que armazena as credenciais do provedor e a configuração. O primeiro argumento de cada função é o nome dessa coleção.

Exemplo de instrução para criar uma coleção nomeada com as credenciais do provedor:

```sql theme={null}
CREATE NAMED COLLECTION ai_credentials AS
    provider = 'openai',
    endpoint = 'https://api.openai.com/v1/chat/completions',
    model = 'gpt-4o-mini',
    api_key = 'sk-...';
```

<div id="named-collection-parameters">
  ### Parâmetros da coleção nomeada
</div>

| Parâmetro     | Tipo   | Padrão | Descrição                                                                                |
| ------------- | ------ | ------ | ---------------------------------------------------------------------------------------- |
| `provider`    | String | —      | Provedor do modelo. Compatível com: `'openai'`, `'anthropic'`. Veja a observação abaixo. |
| `endpoint`    | String | —      | URL do endpoint da API.                                                                  |
| `model`       | String | —      | Nome do modelo (por exemplo, `'gpt-4o-mini'`, `'text-embedding-3-small'`).               |
| `api_key`     | String | —      | Chave de autenticação do provedor.                                                       |
| `max_tokens`  | UInt64 | `1024` | Número máximo de tokens de saída por chamada à API.                                      |
| `api_version` | String | —      | String de versão da API. Usada pelo Anthropic (`'2023-06-01'`).                          |

<Note>
  Qualquer API compatível com OpenAI (por exemplo, vLLM, Ollama, LiteLLM) pode ser usada definindo `provider = 'openai'` e apontando o `endpoint` para o seu serviço.
</Note>

<div id="query-level-settings">
  ### Configurações no nível da consulta
</div>

Todas as configurações relacionadas à IA estão listadas em [Settings](/pt-BR/reference/settings/session-settings) com o prefixo `ai_function_`.

<div id="restricting-endpoint-hosts">
  ### Restringindo hosts de endpoint
</div>

A URL de `endpoint` em uma coleção nomeada de IA é um destino de saída ao qual o servidor se conecta com sua própria identidade, enviando a `api_key` da coleção nomeada nos cabeçalhos da solicitação. Por padrão, o ClickHouse permite qualquer host. Para restringir as funções a um conjunto específico de provedores, configure [`remote_url_allow_hosts`](/pt-BR/reference/settings/server-settings/settings#remote_url_allow_hosts) na configuração do servidor, por exemplo:

```xml theme={null}
<remote_url_allow_hosts>
    <host>api.openai.com</host>
    <host>api.anthropic.com</host>
</remote_url_allow_hosts>
```

Observe que essa configuração vale para todo o servidor e se aplica a todas as funcionalidades que usam HTTP.

<div id="supported-providers">
  ## Provedores compatíveis
</div>

| Provedor  | valor de `provider` | Funções de chat | Observações                    |
| --------- | ------------------- | --------------- | ------------------------------ |
| OpenAI    | `'openai'`          | Sim             | Provedor padrão.               |
| Anthropic | `'anthropic'`       | Sim             | Usa o endpoint `/v1/messages`. |

<div id="observability">
  ## Observabilidade
</div>

A atividade da função de IA é rastreada pelos [ProfileEvents](/pt-BR/reference/system-tables/query_log) do ClickHouse:

| ProfileEvent      | Description                                                                              |
| ----------------- | ---------------------------------------------------------------------------------------- |
| `AIAPICalls`      | Número de solicitações HTTP feitas ao provedor de IA.                                    |
| `AIInputTokens`   | Total de tokens de entrada consumidos.                                                   |
| `AIOutputTokens`  | Total de tokens de saída consumidos.                                                     |
| `AIRowsProcessed` | Número de linhas que receberam um resultado.                                             |
| `AIRowsSkipped`   | Número de linhas ignoradas (cota excedida ou erro com `ai_function_throw_on_error = 0`). |

Consulte estes eventos:

```sql theme={null}
SELECT
    ProfileEvents['AIAPICalls'] AS api_calls,
    ProfileEvents['AIInputTokens'] AS input_tokens,
    ProfileEvents['AIOutputTokens'] AS output_tokens
FROM system.query_log
WHERE query_id = 'query_id'
AND type = 'QueryFinish'
ORDER BY event_time DESC;
```

{/*AUTOGENERATED_START*/}

<div id="aiClassify">
  ## aiClassify
</div>

Introduzido em: v26.4.0

Classifica o texto fornecido em uma das categorias informadas usando um provedor de LLM.

A função envia o texto junto com um prompt de classificação fixo e um formato de resposta com esquema JSON,
restringindo o modelo a retornar exatamente um dos rótulos fornecidos. Quando a resposta é retornada como um objeto JSON
no formato `{"category": "..."}`, o rótulo é extraído, e a string do rótulo é retornada.

O primeiro argumento é uma coleção nomeada que especifica o provedor, o modelo, o endpoint e a chave de API.

**Sintaxe**

```sql theme={null}
aiClassify(collection, text, categories[, temperature])
```

**Aliases**: `AIClassify`

**Argumentos**

* `collection` — Nome de uma coleção nomeada que contém credenciais do provedor e configuração. [`String`](/pt-BR/reference/data-types/string)
* `text` — Texto a ser classificado. [`String`](/pt-BR/reference/data-types/string)
* `categories` — Lista constante de rótulos de categorias possíveis. [`Array(String)`](/pt-BR/reference/data-types/array)
* `temperature` — Temperatura de amostragem que controla a aleatoriedade. Padrão: `0.0`. [`Float64`](/pt-BR/reference/data-types/float)

**Valor retornado**

Um dos rótulos de categoria fornecidos ou o valor padrão do tipo da coluna (string vazia), caso a requisição falhe e `ai_function_throw_on_error` esteja desabilitado. [`String`](/pt-BR/reference/data-types/string)

**Exemplos**

**Classificar o sentimento**

```sql title=Query theme={null}
SELECT aiClassify('ai_credentials', 'I love this product!', ['positive', 'negative', 'neutral'])
```

```response title=Response theme={null}
positive
```

**Classificar uma coluna**

```sql title=Query theme={null}
SELECT body, aiClassify('ai_credentials', body, ['bug', 'question', 'feature']) AS kind FROM issues LIMIT 5
```

```response title=Response theme={null}
```

<div id="aiExtract">
  ## aiExtract
</div>

Introduzido em: v26.4.0

Extrai informações estruturadas de texto não estruturado usando um provedor de LLM.

O terceiro argumento pode ser uma instrução em linguagem natural de forma livre (por exemplo, `'a principal reclamação'`) ou um
schema codificado em JSON no formato `'{"field_a": "description of field a", "field_b": "description of field b"}'`.

No modo de instrução, a função retorna o valor extraído como uma string simples, ou uma string vazia se nada for encontrado.
No modo de schema, a função retorna uma string contendo um objeto JSON cujas chaves correspondem ao schema solicitado; os campos ausentes são `null`.

O primeiro argumento é uma coleção nomeada que especifica o provedor, o modelo, o endpoint e a chave de API.

**Sintaxe**

```sql theme={null}
aiExtract(collection, text, instruction_or_schema[, temperature])
```

**Aliases**: `AIExtract`

**Argumentos**

* `collection` — Nome de uma coleção nomeada que contém credenciais do provedor e a configuração. [`String`](/pt-BR/reference/data-types/string)
* `text` — Texto do qual extrair informações. [`String`](/pt-BR/reference/data-types/string)
* `instruction_or_schema` — Instrução de extração em formato livre ou um objeto JSON constante que descreve os campos a serem extraídos. [`const String`](/pt-BR/reference/data-types/string)
* `temperature` — Temperatura de amostragem que controla a aleatoriedade. Padrão: `0.0`. [`const Float64`](/pt-BR/reference/data-types/float)

**Valor retornado**

Um único valor extraído (modo de instrução) ou uma string contendo um objeto JSON (modo de esquema). Retorna o valor padrão para o tipo da coluna (string vazia) se a requisição falhar e `ai_function_throw_on_error` estiver desativado. [`String`](/pt-BR/reference/data-types/string)

**Exemplos**

**Instrução em formato livre**

```sql title=Query theme={null}
SELECT aiExtract('ai_credentials', 'The package arrived late and was damaged.', 'the main complaint')
```

```response title=Response theme={null}
late and damaged package
```

**Extração de esquema**

```sql title=Query theme={null}
SELECT aiExtract('ai_credentials', review, '{"sentiment": "positive, negative or neutral", "topic": "main topic of the review"}') FROM reviews LIMIT 5
```

```response title=Response theme={null}
```

<div id="aiGenerate">
  ## aiGenerate
</div>

Introduzido em: v26.4.0

Gera texto livre a partir de um prompt usando um provedor de LLM.

A função envia o prompt ao provedor de IA configurado e retorna o texto gerado.
Opcionalmente, é possível fornecer um prompt de sistema para orientar o comportamento do modelo (por exemplo, tom, formato ou função).
Se nenhum prompt de sistema for fornecido, o prompt de sistema padrão será: `You are a helpful assistant. Provide a clear and concise response.`

O primeiro argumento é uma coleção nomeada que especifica o provedor, o modelo, o endpoint e a chave de API.

**Sintaxe**

```sql theme={null}
aiGenerate(collection, prompt[, system_prompt[, temperature]])
```

**Aliases**: `AIGenerate`

**Argumentos**

* `collection` — Nome de uma coleção nomeada que contém credenciais do provedor e configuração. [`String`](/pt-BR/reference/data-types/string)
* `prompt` — O prompt ou a pergunta do usuário a ser enviada ao modelo. [`String`](/pt-BR/reference/data-types/string)
* `system_prompt` — Instrução constante opcional em nível de sistema que orienta o comportamento do modelo (por exemplo, persona, formato de saída), enviada com cada prompt. [`String`](/pt-BR/reference/data-types/string)
* `temperature` — Temperatura de amostragem que controla a aleatoriedade. Padrão: `0.7`. [`Float64`](/pt-BR/reference/data-types/float)

**Valor retornado**

A resposta de texto gerada, ou o valor padrão para o tipo de coluna (string vazia) se a requisição falhar e `ai_function_throw_on_error` estiver desabilitado. [`String`](/pt-BR/reference/data-types/string)

**Exemplos**

**Pergunta simples**

```sql title=Query theme={null}
SELECT aiGenerate('ai_credentials', 'What is 2 + 2? Reply with just the number.')
```

```response title=Response theme={null}
4
```

**Com prompt do sistema**

```sql title=Query theme={null}
SELECT aiGenerate('ai_credentials', 'Explain ClickHouse', 'You are a database expert. Be concise.')
```

```response title=Response theme={null}
```

**Resumir os valores da coluna**

```sql title=Query theme={null}
SELECT article_title, aiGenerate('ai_credentials', concat('Summarize in one sentence: ', article_body)) AS summary FROM articles LIMIT 5
```

```response title=Response theme={null}
```

<div id="aiTranslate">
  ## aiTranslate
</div>

Introduzido em: v26.4.0

Traduz o texto fornecido para o idioma de destino especificado usando um provedor de LLM.

Instruções adicionais de estilo ou dialeto podem ser fornecidas como quarto argumento (por exemplo, `'manter termos técnicos sem tradução'`).

O primeiro argumento é uma coleção nomeada que especifica o provedor, o modelo, o endpoint e a chave de API.

**Sintaxe**

```sql theme={null}
aiTranslate(collection, text, target_language[, instructions[, temperature]])
```

**Aliases**: `AITranslate`

**Argumentos**

* `collection` — Nome de uma coleção nomeada que contém credenciais do provedor e configuração. [`String`](/pt-BR/reference/data-types/string)
* `text` — Texto a ser traduzido. [`String`](/pt-BR/reference/data-types/string)
* `target_language` — Nome do idioma de destino ou código BCP-47 (por exemplo, `'French'`, `'es-MX'`). [`String`](/pt-BR/reference/data-types/string)
* `instructions` — Instruções adicionais constantes, opcionais, para o tradutor. [`String`](/pt-BR/reference/data-types/string)
* `temperature` — Temperatura de amostragem que controla a aleatoriedade. Padrão: `0.3`. [`Float64`](/pt-BR/reference/data-types/float)

**Valor retornado**

O texto traduzido ou o valor padrão para o tipo da coluna (string vazia), caso a solicitação falhe e `ai_function_throw_on_error` esteja desabilitado. [`String`](/pt-BR/reference/data-types/string)

**Exemplos**

**Traduzir para o francês**

```sql title=Query theme={null}
SELECT aiTranslate('ai_credentials', 'Hello, world!', 'French')
```

```response title=Response theme={null}
Bonjour le monde!
```

**Traduza para o japonês seguindo as instruções de estilo**

```sql title=Query theme={null}
SELECT aiTranslate('ai_credentials', body, 'Japanese', 'Use polite form (desu/masu)') FROM articles LIMIT 5
```

```response title=Response theme={null}
```