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

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

​

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

Todas as configurações relacionadas à IA estão listadas em Settings com o prefixo ai_function_.

​

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

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

Sintaxe

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
• 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('ai_credentials', 'I love this product!', ['positive', 'negative', 'neutral'])

Response

positive

Classificar uma coluna

Query

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

Response

​

aiExtract

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

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
• 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('ai_credentials', 'The package arrived late and was damaged.', 'the main complaint')

Response

late and damaged package

Extração de esquema

Query

SELECT aiExtract('ai_credentials', 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.

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

Sintaxe

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
• 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('ai_credentials', 'What is 2 + 2? Reply with just the number.')

Response

4

Com prompt do sistema

Query

SELECT aiGenerate('ai_credentials', 'Explain ClickHouse', 'You are a database expert. Be concise.')

Response

Resumir os valores da coluna

Query

SELECT article_title, aiGenerate('ai_credentials', 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 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

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
• 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('ai_credentials', 'Hello, world!', 'French')

Response

Bonjour le monde!

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

Query

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

Response