Funções de IA

Documentação sobre 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 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, ai_function_max_output_tokens_per_query) e chamadas de API (ai_function_max_api_calls_per_query).
• Retentativas com backoff: Falhas transitórias são repetidas (ai_function_max_retries) com backoff exponencial (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. Para definir qual coleção nomeada será usada para as credenciais, use a configuração ai_function_credentials.

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

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:

-- 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. Todas as configurações relacionadas à IA estão listadas em 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:

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:

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:

<profiles>
    <default>
        <allow_experimental_ai_functions>1</allow_experimental_ai_functions>
        <ai_function_credentials>my_ai_credentials</ai_function_credentials>
    </default>
</profiles>

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 na configuração do servidor, por exemplo:

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

​

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 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:

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;

​

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

aiClassify(text, categories[, temperature])

Aliases: AIClassify

Argumentos

• text — Texto a ser classificado. String
• categories — Lista constante de rótulos de categorias possíveis. Array(String)
• temperature — Temperatura de amostragem que controla a aleatoriedade. Padrão: 0.0. Float64

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

Exemplos

Classificar o sentimento

Query

SELECT aiClassify('I love this product!', ['positive', 'negative', 'neutral']) SETTINGS ai_function_credentials = 'my_ai_credentials'

Response

positive

Classificar uma coluna

Query

SELECT body, aiClassify(body, ['bug', 'question', 'feature']) AS kind FROM issues LIMIT 5

Response

​

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

aiEmbed(text[, dimensions])

Argumentos

• text — Texto para gerar o embedding. String
• dimensions — Dimensionalidade de destino opcional para o vetor de saída. 0 ou omitido significa o tamanho nativo do modelo. UInt64

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)

Exemplos

Gerar embedding de uma única string

Query

SELECT aiEmbed('Hello world') SETTINGS ai_function_credentials = 'my_ai_credentials'

Response

Com dimensões explícitas

Query

SELECT aiEmbed('Hello world', 256) SETTINGS ai_function_credentials = 'my_ai_credentials'

Response

Gerar embeddings para uma coluna de textos

Query

SELECT aiEmbed(title, 256) FROM articles LIMIT 10

Response

​

aiExtract

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

aiExtract(text, instruction_or_schema[, temperature])

Aliases: AIExtract

Argumentos

• text — Texto do qual extrair informações. 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
• temperature — Temperatura de amostragem que controla a aleatoriedade. Padrão: 0.0. const Float64

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

Exemplos

Instrução em formato livre

Query

SELECT aiExtract('The package arrived late and was damaged.', 'the main complaint') SETTINGS ai_function_credentials = 'my_ai_credentials'

Response

late and damaged package

Extração de esquema

Query

SELECT aiExtract(review, '{"sentiment": "positive, negative or neutral", "topic": "main topic of the review"}') FROM reviews LIMIT 5

Response

​

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

aiGenerate(prompt[, system_prompt[, temperature]])

Aliases: AIGenerate

Argumentos

• prompt — O prompt ou a pergunta do usuário a ser enviada ao modelo. 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
• temperature — Temperatura de amostragem que controla a aleatoriedade. Padrão: 0.7. Float64

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

Exemplos

Pergunta simples

Query

SELECT aiGenerate('What is 2 + 2? Reply with just the number.') SETTINGS ai_function_credentials = 'my_ai_credentials'

Response

4

Com prompt do sistema

Query

SELECT aiGenerate('Explain ClickHouse', 'You are a database expert. Be concise.') SETTINGS ai_function_credentials = 'my_ai_credentials'

Response

Resumir os valores da coluna

Query

SELECT article_title, aiGenerate(concat('Summarize in one sentence: ', article_body)) AS summary FROM articles LIMIT 5

Response

​

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

aiTranslate(text, target_language[, instructions[, temperature]])

Aliases: AITranslate

Argumentos

• text — Texto a ser traduzido. String
• target_language — Nome do idioma de destino ou código BCP-47 (por exemplo, 'French', 'es-MX'). String
• instructions — Instruções adicionais constantes, opcionais, para o tradutor. String
• temperature — Temperatura de amostragem que controla a aleatoriedade. Padrão: 0.3. Float64

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

Exemplos

Traduzir para o francês

Query

SELECT aiTranslate('Hello, world!', 'French') SETTINGS ai_function_credentials = 'my_ai_credentials'

Response

Bonjour le monde!

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

Query

SELECT aiTranslate(body, 'Japanese', 'Use polite form (desu/masu)') FROM articles LIMIT 5

Response