> ## Documentation Index
> Fetch the complete documentation index at: https://private-7c7dfe99-mintlify-fbfa8bee.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...
As funções de IA são experimentais. Defina [`allow_experimental_ai_functions`](/pt-BR/reference/settings/session-settings#allow_experimental_ai_functions) para ativá-las.
As funções de IA podem retornar saídas imprevisíveis. O resultado dependerá muito da qualidade do prompt e do modelo usado.
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)).
## Configuração
As funções de IA obtêm as credenciais do provedor e a configuração a partir de uma [**coleção nomeada**](/pt-BR/concepts/features/configuration/server-config/named-collections). Para definir qual coleção nomeada será usada para as credenciais, use a configuração [`ai_function_credentials`](/pt-BR/reference/settings/session-settings#ai_function_credentials).
Exemplo de instrução para criar uma coleção nomeada com as credenciais do provedor:
```sql theme={null}
CREATE NAMED COLLECTION my_ai_credentials AS
provider = 'openai',
endpoint = 'https://api.openai.com/v1/chat/completions',
model = 'gpt-4o-mini',
api_key = 'sk-...';
```
Selecione a coleção com a configuração `ai_function_credentials`, para a sessão ou para uma única consulta:
```sql theme={null}
-- For the session:
SET allow_experimental_ai_functions = 1;
SET ai_function_credentials = 'my_ai_credentials';
SELECT aiClassify('I love this product!', ['positive', 'negative', 'neutral']);
-- Or for a single query:
SELECT aiClassify('I love this product!', ['positive', 'negative', 'neutral'])
SETTINGS allow_experimental_ai_functions = 1, ai_function_credentials = 'my_ai_credentials';
```
Quando `ai_function_credentials` está vazio (o padrão), uma exceção é lançada.
### Parâmetros da coleção nomeada
| 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. Opcional: quando omitida, o header de autenticação não é enviado, o que permite apontar para servidores compatíveis com OpenAI que não exigem autenticação. |
| `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'`). |
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.
### Configurações no nível da consulta
A coleção nomeada a ser usada é controlada pela configuração [`ai_function_credentials`](/pt-BR/reference/settings/session-settings#ai_function_credentials). Todas as configurações relacionadas à IA estão listadas em [Settings](/pt-BR/reference/settings/session-settings) com o prefixo `ai_function_`.
### Uso em colunas `DEFAULT` e `MATERIALIZED`
A configuração `ai_function_credentials` é lida quando a expressão padrão é avaliada, NÃO quando a coluna é definida. O nome da coleção não fica armazenado na definição da coluna:
```sql theme={null}
CREATE TABLE t (id UInt32, doc String, vector Array(Float32) DEFAULT aiEmbed(doc)) ...;
-- The stored default is `aiEmbed(doc)`; no collection is captured.
```
A avaliação da expressão exige três coisas: `allow_experimental_ai_functions` e `ai_function_credentials` devem estar definidos, e o usuário que a avalia deve ter `GRANT NAMED COLLECTION` na collection (a resolução das credentials faz uma verificação de acesso a `NAMED COLLECTION`). A ausência de qualquer um deles gera uma exceção (`SUPPORT_IS_DISABLED`, um erro de credentials vazias ou `ACCESS_DENIED`).
Uma coluna `DEFAULT` é avaliada em `INSERT`, portanto ambas as configurações devem estar definidas na sessão ou consulta que faz a inserção:
```sql theme={null}
GRANT NAMED COLLECTION ON my_ai_credentials TO user;
SET allow_experimental_ai_functions = 1;
SET ai_function_credentials = 'my_ai_credentials';
INSERT INTO t (id, doc) VALUES (1, 'hello');
```
Para fazer com que essas tabelas permitam inserções sem precisar definir isso por sessão, defina ambas em um [perfil de configurações](/pt-BR/concepts/features/configuration/settings/settings-profiles):
```xml theme={null}
1
my_ai_credentials
```
Uma coluna `MATERIALIZED` é calculada durante o `INSERT`, como uma coluna `DEFAULT`, e também é recalculada por mutações, como `ALTER TABLE ... MATERIALIZE COLUMN`. As mutações são executadas fora da sessão de um usuário e não herdam a cláusula `SETTINGS` de uma consulta, mas herdam as configurações de um perfil de configurações. Defina ambas as configurações em um perfil de configurações e conceda `NAMED COLLECTION` ao proprietário da tabela para que a recomputação acionada por mutações seja concluída com êxito.
### Restringindo hosts de endpoint
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, potencialmente enviando (se especificada) 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}
api.openai.com
api.anthropic.com
```
Observe que essa configuração vale para todo o servidor e se aplica a todas as funcionalidades que usam HTTP.
## Provedores compatíveis
| Provedor | valor de `provider` | Funções de chat | Observações |
| --------- | ------------------- | --------------- | ------------------------------ |
| OpenAI | `'openai'` | Sim | Provedor padrão. |
| Anthropic | `'anthropic'` | Sim | Usa o endpoint `/v1/messages`. |
## Observabilidade
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*/}
## aiClassify
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.
As credenciais do provedor e a configuração são obtidas da coleção nomeada especificada pela configuração `ai_function_credentials`.
**Sintaxe**
```sql theme={null}
aiClassify(text, categories[, temperature])
```
**Aliases**: `AIClassify`
**Argumentos**
* `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('I love this product!', ['positive', 'negative', 'neutral']) SETTINGS ai_function_credentials = 'my_ai_credentials'
```
```response title=Response theme={null}
positive
```
**Classificar uma coluna**
```sql title=Query theme={null}
SELECT body, aiClassify(body, ['bug', 'question', 'feature']) AS kind FROM issues LIMIT 5
```
```response title=Response theme={null}
```
## aiEmbed
Introduzido em: v26.6.0
Gera um vetor de embedding para o texto fornecido usando o provedor de IA configurado.
A função envia o texto para o endpoint de embedding configurado e retorna o vetor resultante como `Array(Float32)`.
Dentro de um único bloco de linhas, as entradas são agrupadas em lotes de até
[`ai_function_embedding_max_batch_size`](/pt-BR/reference/settings/session-settings#ai_function_embedding_max_batch_size)
itens por requisição HTTP para reduzir a sobrecarga por chamada.
As credenciais do provedor e a configuração são obtidas da coleção nomeada especificada pela configuração `ai_function_credentials`.
O argumento opcional `dimensions`, quando compatível com o modelo (por exemplo, `text-embedding-3-*` da OpenAI),
solicita um vetor do tamanho especificado; caso contrário, o tamanho nativo do modelo é retornado.
**Sintaxe**
```sql theme={null}
aiEmbed(text[, dimensions])
```
**Argumentos**
* `text` — Texto para gerar o embedding. [`String`](/pt-BR/reference/data-types/string)
* `dimensions` — Dimensionalidade de destino opcional para o vetor de saída. `0` ou omitido significa o tamanho nativo do modelo. [`UInt64`](/pt-BR/reference/data-types/int-uint)
**Valor retornado**
O vetor de embedding, ou um array vazio se a entrada for NULL ou vazia, se a solicitação falhar e `ai_function_throw_on_error` estiver desabilitado, ou se uma cota for excedida com `ai_function_throw_on_quota_exceeded` desabilitado. [`Array(Float32)`](/pt-BR/reference/data-types/array)
**Exemplos**
**Gerar embedding de uma única string**
```sql title=Query theme={null}
SELECT aiEmbed('Hello world') SETTINGS ai_function_credentials = 'my_ai_credentials'
```
```response title=Response theme={null}
```
**Com dimensões explícitas**
```sql title=Query theme={null}
SELECT aiEmbed('Hello world', 256) SETTINGS ai_function_credentials = 'my_ai_credentials'
```
```response title=Response theme={null}
```
**Gerar embeddings para uma coluna de textos**
```sql title=Query theme={null}
SELECT aiEmbed(title, 256) FROM articles LIMIT 10
```
```response title=Response theme={null}
```
Introduzido em: v26.4.0
Extrai informações estruturadas de texto não estruturado usando um provedor de LLM.
O segundo 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`.
As credenciais do provedor e a configuração são obtidas da coleção nomeada especificada na configuração `ai_function_credentials`.
**Sintaxe**
```sql theme={null}
aiExtract(text, instruction_or_schema[, temperature])
```
**Aliases**: `AIExtract`
**Argumentos**
* `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('The package arrived late and was damaged.', 'the main complaint') SETTINGS ai_function_credentials = 'my_ai_credentials'
```
```response title=Response theme={null}
late and damaged package
```
**Extração de esquema**
```sql title=Query theme={null}
SELECT aiExtract(review, '{"sentiment": "positive, negative or neutral", "topic": "main topic of the review"}') FROM reviews LIMIT 5
```
```response title=Response theme={null}
```
## aiGenerate
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.`
As credenciais do provedor e a configuração são obtidas da coleção nomeada especificada na configuração `ai_function_credentials`.
**Sintaxe**
```sql theme={null}
aiGenerate(prompt[, system_prompt[, temperature]])
```
**Aliases**: `AIGenerate`
**Argumentos**
* `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('What is 2 + 2? Reply with just the number.') SETTINGS ai_function_credentials = 'my_ai_credentials'
```
```response title=Response theme={null}
4
```
**Com prompt do sistema**
```sql title=Query theme={null}
SELECT aiGenerate('Explain ClickHouse', 'You are a database expert. Be concise.') SETTINGS ai_function_credentials = 'my_ai_credentials'
```
```response title=Response theme={null}
```
**Resumir os valores da coluna**
```sql title=Query theme={null}
SELECT article_title, aiGenerate(concat('Summarize in one sentence: ', article_body)) AS summary FROM articles LIMIT 5
```
```response title=Response theme={null}
```
## aiTranslate
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 terceiro argumento (por exemplo, `'manter termos técnicos sem tradução'`).
As credenciais do provedor e a configuração são obtidas da coleção nomeada especificada pela configuração `ai_function_credentials`.
**Sintaxe**
```sql theme={null}
aiTranslate(text, target_language[, instructions[, temperature]])
```
**Aliases**: `AITranslate`
**Argumentos**
* `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('Hello, world!', 'French') SETTINGS ai_function_credentials = 'my_ai_credentials'
```
```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(body, 'Japanese', 'Use polite form (desu/masu)') FROM articles LIMIT 5
```
```response title=Response theme={null}
```