Funciones de IA - ClickHouse Documentation

Las funciones de IA son funciones integradas de ClickHouse que puedes usar para invocar IA o generar embeddings con los que trabajar con tus datos, extraer información, clasificar datos, etc…

Las funciones de IA son experimentales. Configura allow_experimental_ai_functions para habilitarlas.

Las funciones de IA pueden devolver resultados impredecibles. El resultado dependerá en gran medida de la calidad del prompt y del modelo utilizado.

Todas las funciones comparten una infraestructura común que proporciona:

Aplicación de cuotas: Límites por consulta de tokens (ai_function_max_input_tokens_per_query, ai_function_max_output_tokens_per_query) y llamadas a la API (ai_function_max_api_calls_per_query).
Reintentos con backoff: Los fallos transitorios se reintentan (ai_function_max_retries) con backoff exponencial (ai_function_retry_initial_delay_ms).

Configuración

Las funciones de AI hacen referencia a una colección nombrada que almacena las credenciales del proveedor y la configuración. Se pueden crear y usar distintas colecciones nombradas para diferentes funciones o llamadas a funciones. Por ejemplo, quizá quiera definir una colección nombrada distinta para usar con las funciones de texto (aiGenerate, aiClassify, aiExtract, aiTranslate) en lugar de la función aiEmbed, ya que requieren endpoints diferentes y normalmente usan modelos distintos. Ejemplo de sentencia para crear una colección nombrada con credenciales del proveedor: una con un endpoint de chat y otra con un endpoint de embedding:

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

-- `aiEmbed` does not read `model` from the named collection; pass it as a positional argument instead.
-- Defining `model` in an `aiEmbed` collection is an error, not silently ignored.
CREATE NAMED COLLECTION ai_embedding_credentials AS
    provider = 'openai',
    endpoint = 'https://api.openai.com/v1/embeddings',
    api_key = 'sk-...';

Parámetros de la colección nombrada

Parámetro	Tipo	Predeterminado	Descripción
`provider`	String	—	Proveedor del modelo. Admitidos: `'openai'`, `'anthropic'`. Consulte la nota a continuación.
`endpoint`	String	—	URL del endpoint de la API.
`model`	String	—	Nombre del modelo (p. ej. `'gpt-4o-mini'`). Lo utilizan las funciones de texto; `aiEmbed` requiere `model` como argumento posicional y genera un error si `model` se especifica en la colección nombrada.
`api_key`	String	—	Clave de autenticación del proveedor. Opcional: cuando se omite, no se envía el `header` de autenticación, lo que permite usar servidores compatibles con OpenAI que no requieren autenticación.
`max_tokens`	UInt64	`1024`	Número máximo de tokens de salida por llamada a la API.
`api_version`	String	—	Cadena de versión de la API. La utiliza Anthropic (`'2023-06-01'`).

Se puede usar cualquier API compatible con OpenAI (p. ej. vLLM, Ollama, LiteLLM) configurando provider = 'openai' y apuntando endpoint a su servicio.

Selección de credenciales

Una función determina la colección nombrada que debe usar según, en este orden:

la clave credentials de su mapa de parámetros, cuando está presente;
en caso contrario, la configuración predeterminada de credenciales aplicable:
- ai_function_text_default_credentials para las funciones de texto (aiGenerate, aiClassify, aiExtract, aiTranslate);
- ai_function_embedding_default_credentials para aiEmbed.

Si no se configura ninguna de las dos, la llamada falla. Las funciones de texto y de embeddings usan configuraciones predeterminadas distintas porque un endpoint de chat-completions difiere de uno de embeddings.

SET ai_function_text_default_credentials = 'ai_text_credentials';

-- Uses ai_text_credentials from the setting:
SELECT aiGenerate('What is 2 + 2? Reply with just the number.');

-- Overrides the default for this call:
SELECT aiGenerate('Bonjour', map('credentials', 'other_credentials'));

Mapa de parámetros

Cada función acepta opcionalmente un Map(String, String) de parámetros al final. Todos los valores son cadenas (ponga entre comillas los números, por ejemplo, '0.2'). Las claves desconocidas se rechazan. Si una clave está presente, sobrescribe el valor correspondiente de la colección nombrada; si una clave no está presente, se usa el valor de la colección nombrada (para model/max_tokens) o el valor predeterminado integrado. La excepción es aiEmbed, que toma model como un argumento posicional obligatorio (aiEmbed(text, model[, params])) y genera un error si, en su lugar, se establece en el mapa de parámetros o en la colección nombrada. Los siguientes parámetros son comunes a todas las funciones de IA:

Clave	Descripción
`credentials`	Colección nombrada que se va a usar (consulte arriba).
`model`	Sobrescribe el `model` de la colección (solo para funciones de texto; `aiEmbed` toma `model` como un argumento posicional obligatorio, no como una clave del mapa).

Las funciones individuales aceptan parámetros adicionales específicos de cada función (como max_tokens, temperature, system_prompt, instructions y dimensions). Consulte la referencia de cada función a continuación para ver qué parámetros acepta y sus valores predeterminados.

SELECT aiGenerate(body, map('temperature', '0.2', 'system_prompt', 'You are terse.')) FROM articles;

Configuración a nivel de consulta

Toda la configuración relacionada con la IA se enumera en Configuración con el prefijo ai_function_.

Restricción de hosts de endpoint

La URL de endpoint en una colección nombrada de IA es un destino saliente al que el servidor se conecta con su propia identidad, y puede enviar (si se especifica) la api_key de la colección nombrada en los encabezados de la solicitud. De forma predeterminada, ClickHouse permite cualquier host. Para restringir las funciones a un conjunto específico de proveedores, configure remote_url_allow_hosts en la configuración del servidor, por ejemplo:

<remote_url_allow_hosts>
    <host>api.openai.com</host>
    <host>api.anthropic.com</host>
</remote_url_allow_hosts>

Ten en cuenta que esta configuración es global para el servidor y se aplica a todas las funciones que usan HTTP.

Seguridad del transporte (HTTP vs HTTPS)

El transporte se determina únicamente por el esquema de la URL del endpoint. No hay cifrado del payload de la solicitud a nivel de la aplicación; la protección de los datos en tránsito depende por completo del esquema:

https:// — la conexión usa TLS. El cuerpo de la solicitud (texto de entrada, prompts) y la api_key en el encabezado de la solicitud se cifran en tránsito, y se valida el certificado del proveedor. Use esto para cualquier proveedor remoto.
http:// — la conexión no está cifrada. El cuerpo de la solicitud y la api_key se envían en texto sin formato. Use esto solo para un proveedor de confianza en una red privada (p. ej., una instancia local de vLLM o Ollama).

Las funciones de IA no fuerzan HTTPS: se acepta un endpoint http:// y envía datos sin cifrar. Actualmente no hay ninguna configuración del lado del servidor que rechace endpoints de IA en texto sin formato — remote_url_allow_hosts restringe solo el host de destino y no inspecciona el esquema de la URL, por lo que un endpoint http:// hacia un host permitido igualmente pasa. Para garantizar el transporte cifrado, configure colecciones nombradas con endpoints https://. Tenga en cuenta que, en cualquiera de los dos casos, el proveedor recibe los datos de entrada en texto sin formato después de la terminación de TLS; TLS protege los datos solo en la ruta de red entre el servidor y el proveedor.

Proveedores compatibles

Proveedor	Valor de `provider`	Funciones de chat	Notas
OpenAI	`'openai'`	Sí	Proveedor por defecto.
Anthropic	`'anthropic'`	Sí	Usa el endpoint `/v1/messages`.

Observabilidad

La actividad de la función de IA se supervisa mediante los ProfileEvents de ClickHouse:

ProfileEvent	Description
`AIAPICalls`	Número de solicitudes HTTP realizadas al proveedor de IA.
`AIInputTokens`	Total de tokens de entrada consumidos.
`AIOutputTokens`	Total de tokens de salida consumidos.
`AIRowsProcessed`	Número de filas que recibieron un resultado.
`AIRowsSkipped`	Número de filas omitidas (se superó la cuota o hubo un error con `ai_function_throw_on_error = 0`).

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

Introducido en: v26.4.0 Clasifica el texto dado en una de las categorías proporcionadas mediante un proveedor de LLM. La función envía el texto junto con un prompt de clasificación fijo y un formato de respuesta con esquema JSON que obliga al modelo a devolver exactamente una de las etiquetas proporcionadas. Cuando la respuesta se devuelve como un objeto JSON con la forma {"category": "..."}, se extrae la etiqueta y se devuelve su cadena de texto. Las credenciales (una colección nombrada que especifica el proveedor, el modelo, el endpoint y, opcionalmente, una API key) se toman de la clave credentials del mapa de parámetros opcional, o de la configuración ai_function_text_default_credentials cuando el mapa la omite. Sintaxis

aiClassify(text, categories[, params])

Alias: AIClassify Argumentos

text — Texto que se va a clasificar. String
categories — Lista constante de etiquetas de categorías candidatas. Array(String)
params — Map(String, String) constante opcional de parámetros. Claves específicas de la función: temperature (temperatura de muestreo que controla la aleatoriedad; valor predeterminado 0.0), max_tokens (número máximo de tokens de salida por llamada; valor predeterminado 1024). También se aplican los parámetros comunes credentials y model (consulte Funciones de IA). Map(String, String)

Valor devuelto Una de las etiquetas de categoría proporcionadas, o el valor predeterminado del tipo de columna (cadena vacía) si la solicitud falla y ai_function_throw_on_error está deshabilitada. String Ejemplos Clasificación de sentimiento

Query

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

Response

positive

Clasificar una columna con credenciales explícitas

Query

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

aiEmbed

Introducido en: v26.6.0 Genera un vector de embedding para el texto proporcionado mediante el proveedor de IA configurado. La función envía el texto al endpoint de embeddings configurado y devuelve el vector resultante como Array(Float32). Dentro de un mismo bloque de filas, las entradas se agrupan en lotes de hasta ai_function_embedding_max_batch_size elementos por solicitud HTTP para reducir la sobrecarga de cada llamada. Las credenciales (una colección nombrada que especifica el proveedor, el endpoint y, opcionalmente, una API key) se toman de la clave credentials del mapa de parámetros, o de la configuración ai_function_embedding_default_credentials cuando el mapa la omite. Ten en cuenta que aiEmbed usa una configuración predeterminada de credenciales distinta de la de las funciones de texto, ya que un endpoint de embeddings difiere de uno de chat. model es un argumento posicional obligatorio (un String constante). A diferencia de las funciones de texto, aiEmbed no lee model de la colección nombrada ni del mapa de parámetros. Una colección nombrada que define model se rechaza en lugar de ignorarse silenciosamente. El parámetro opcional dimensions, cuando el modelo lo admite (por ejemplo, text-embedding-3-* de OpenAI), solicita un vector del tamaño indicado; de lo contrario, se devuelve el tamaño nativo del modelo. Sintaxis

aiEmbed(text, model[, params])

Argumentos

text — Texto que se convertirá en embedding. String
model — Nombre del modelo de embedding. const String
params — Map(String, String) constante opcional de parámetros. Clave específica de la función: dimensions (dimensionalidad de destino del vector de salida; 0 o si se omite significa el tamaño nativo del modelo). El parámetro común credentials también se admite (consulta Funciones de IA). Map(String, String)

Valor devuelto El vector de embedding, o un array vacío si la entrada es NULL o está vacía, la petición falló y ai_function_throw_on_error está desactivado, o se superó una cuota con ai_function_throw_on_quota_exceeded desactivado. Array(Float32) Ejemplos Generar el embedding de una sola cadena (credentials puede omitirse si la configuración ai_function_embedding_default_credentials está establecida)

Query

SELECT aiEmbed('Hello world', 'text-embedding-3-small', map('credentials', 'ai_embedding_credentials'))

Con dimensiones explícitas

Query

SELECT aiEmbed('Hello world', 'text-embedding-3-small', map('credentials', 'ai_embedding_credentials', 'dimensions', '256'))

Insertar una columna de texto

Query

SELECT aiEmbed(title, 'text-embedding-3-small', map('credentials', 'ai_embedding_credentials', 'dimensions', '256')) FROM articles LIMIT 10

aiExtract

Introducido en: v26.4.0 Extrae información estructurada de texto no estructurado usando un proveedor de LLM. El tercer argumento puede ser una instrucción en lenguaje natural de formato libre (p. ej., 'the main complaint') o un esquema codificado en JSON con la forma '{"field_a": "description of field a", "field_b": "description of field b"}'. En el modo de instrucción, la función devuelve el valor extraído como una cadena de texto simple, o una cadena vacía si no se encuentra nada. En el modo de esquema, la función devuelve una cadena que contiene un objeto JSON cuyas claves coinciden con el esquema solicitado; los campos ausentes son null. Las credenciales (una colección nombrada que especifica el proveedor, el modelo, el endpoint y, opcionalmente, una API key) se toman de la clave credentials del mapa de parámetros opcional, o de la configuración ai_function_text_default_credentials cuando el mapa la omite. Sintaxis

aiExtract(text, instruction_or_schema[, params])

Alias: AIExtract Argumentos

text — Texto del que extraer información. String
instruction_or_schema — Instrucción de extracción en formato libre, o un objeto JSON constante que describe los campos que se deben extraer. const String
params — Map(String, String) constante opcional de parámetros. Claves específicas de la función: temperature (temperatura de muestreo que controla la aleatoriedad; valor predeterminado 0.0), max_tokens (máximo de tokens de salida por llamada; valor predeterminado 1024). Los parámetros comunes credentials y model también se aplican (consulte Funciones de IA). Map(String, String)

Valor devuelto Un único valor extraído (modo de instrucción) o una cadena con un objeto JSON (modo de esquema). Devuelve el valor predeterminado para el tipo de columna (cadena vacía) si la solicitud falló y ai_function_throw_on_error está deshabilitado. String Ejemplos Instrucción en formato libre

Query

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

Response

late and damaged package

Extracción del esquema

Query

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

aiGenerate

Introducido en: v26.4.0 Genera contenido de texto libre a partir de un prompt mediante un proveedor de LLM. La función envía el prompt al proveedor de IA configurado y devuelve el texto generado. Las credenciales (una colección nombrada que especifica el proveedor, el modelo, el endpoint y, opcionalmente, una API key) se toman de la clave credentials del mapa de parámetros opcional, o de la configuración ai_function_text_default_credentials cuando el mapa no la incluye. El mapa de parámetros opcional también puede establecer system_prompt (una instrucción que guía el comportamiento del modelo, p. ej., tono, formato y rol), temperature, max_tokens y model. Si system_prompt no está establecido, el valor predeterminado es: You are a helpful assistant. Provide a clear and concise response. Sintaxis

aiGenerate(prompt[, params])

Alias: AIGenerate Argumentos

prompt — El prompt o la pregunta del usuario que se enviará al modelo. String
params — Map(String, String) constante opcional de parámetros. Claves específicas de la función: temperature (temperatura de muestreo que controla la aleatoriedad; valor predeterminado 0.7), max_tokens (máximo de tokens de salida por llamada; valor predeterminado 1024), system_prompt (instrucción constante a nivel de sistema que guía el comportamiento del modelo; de forma predeterminada, un prompt genérico de asistente). También se aplican los parámetros comunes credentials y model (consulte Funciones de IA). Map(String, String)

Valor devuelto La respuesta de texto generada, o el valor predeterminado del tipo de columna (cadena vacía) si la solicitud falla y ai_function_throw_on_error está deshabilitado. String Ejemplos Pregunta simple

Query

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

Response

Con credenciales explícitas y prompt del sistema

Query

SELECT aiGenerate('Explain ClickHouse', map('credentials', 'ai_text_credentials', 'system_prompt', 'You are a database expert. Be concise.'))

Resumir los valores de una columna

Query

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

aiTranslate

Introducido en: v26.4.0 Traduce el texto proporcionado al idioma de destino especificado mediante un proveedor de LLM. Se pueden proporcionar instrucciones adicionales de estilo o dialecto mediante la clave instructions del mapa de parámetros (por ejemplo, 'mantener los términos técnicos sin traducir'). Las credenciales (una colección nombrada que especifica el proveedor, el modelo, el endpoint y, opcionalmente, una API key) se obtienen de la clave credentials del mapa de parámetros opcional, o de la configuración ai_function_text_default_credentials cuando el mapa la omite. Sintaxis

aiTranslate(text, target_language[, params])

Alias: AITranslate Argumentos

text — Texto que se debe traducir. String
target_language — Nombre del idioma de destino o código BCP-47 (p. ej., 'French', 'es-MX'). String
params — Map(String, String) constante opcional de parámetros. Claves específicas de la función: temperature (temperatura de muestreo que controla la aleatoriedad; valor predeterminado 0.3), max_tokens (número máximo de tokens de salida por llamada; valor predeterminado 1024), instructions (instrucciones adicionales de estilo o dialecto para el traductor). También se aplican los parámetros comunes credentials y model (consulta Funciones de IA). Map(String, String)

Valor devuelto El texto traducido, o el valor predeterminado del tipo de columna (cadena vacía) si la solicitud falla y ai_function_throw_on_error está deshabilitado. String Ejemplos Traducir al francés

Query

SELECT aiTranslate('Hello, world!', 'French')

Response

Bonjour le monde!

Traducir al japonés siguiendo las instrucciones de estilo

Query

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

​Configuración

​Parámetros de la colección nombrada

​Selección de credenciales

​Mapa de parámetros

​Configuración a nivel de consulta

​Restricción de hosts de endpoint

​Seguridad del transporte (HTTP vs HTTPS)

​Proveedores compatibles

​Observabilidad

​aiClassify

​aiEmbed

​aiExtract

​aiGenerate

​aiTranslate

Configuración

Parámetros de la colección nombrada

Selección de credenciales

Mapa de parámetros

Configuración a nivel de consulta

Restricción de hosts de endpoint

Seguridad del transporte (HTTP vs HTTPS)

Proveedores compatibles

Observabilidad

aiClassify

aiEmbed

aiExtract

aiGenerate

aiTranslate