Fonctions d'IA

Documentation des fonctions d’IA

Les fonctions d’IA sont des fonctions intégrées de ClickHouse que vous pouvez utiliser pour faire appel à l’IA ou générer des embeddings afin de travailler avec vos données, d’en extraire des informations, de classer des données, etc.

Les fonctions d’IA sont expérimentales. Définissez allow_experimental_ai_functions pour les activer.

Les fonctions d’IA peuvent produire des résultats imprévisibles. Le résultat dépendra fortement de la qualité du prompt et du modèle utilisés.

Toutes les fonctions partagent une infrastructure commune qui fournit :

• Application des quotas : limites par requête sur les tokens (ai_function_max_input_tokens_per_query, ai_function_max_output_tokens_per_query) et sur les appels d’API (ai_function_max_api_calls_per_query).
• Nouvelle tentative avec backoff : les échecs temporaires sont réessayés (ai_function_max_retries) avec un backoff exponentiel (ai_function_retry_initial_delay_ms).

​

Configuration

Les fonctions d’IA s’appuient sur une collection nommée qui stocke les identifiants du fournisseur et la configuration. Le premier argument de chaque fonction est le nom de cette collection.

Exemple d’instruction pour créer une collection nommée avec les identifiants du fournisseur :

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

​

Paramètres de la collection nommée

Paramètre	Type	Par défaut	Description
provider	String	—	Fournisseur du modèle. Valeurs prises en charge : 'openai', 'anthropic'. Voir la note ci-dessous.
endpoint	String	—	URL du point de terminaison de l’API.
model	String	—	Nom du modèle (par ex. 'gpt-4o-mini', 'text-embedding-3-small').
api_key	String	—	Clé d’authentification du fournisseur. Facultatif : si elle est omise, l’en-tête d’authentification n’est pas envoyé, ce qui permet de cibler des serveurs compatibles OpenAI qui ne nécessitent pas d’authentification.
max_tokens	UInt64	1024	Nombre maximal de tokens de sortie par appel d’API.
api_version	String	—	Chaîne de version de l’API. Utilisée par Anthropic ('2023-06-01').

Toute API compatible OpenAI (par ex. vLLM, Ollama, LiteLLM) peut être utilisée en définissant provider = 'openai' et en pointant endpoint vers votre service.

​

Paramètres au niveau de la requête

Tous les paramètres liés à l’IA sont répertoriés dans Paramètres sous le préfixe ai_function_.

​

Restreindre les hôtes de point de terminaison

L’URL endpoint d’une collection nommée d’IA est une destination sortante à laquelle le serveur se connecte avec sa propre identité, en transmettant potentiellement (si elle est spécifiée) l’api_key de la collection nommée dans les en-têtes de requête. Par défaut, ClickHouse autorise n’importe quel hôte. Pour limiter les fonctions à un ensemble spécifique de fournisseurs, configurez remote_url_allow_hosts dans la configuration du serveur, par exemple :

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

Notez que ce paramètre s’applique à l’ensemble du serveur et à toutes les fonctionnalités utilisant HTTP.

​

Fournisseurs pris en charge

Fournisseur	valeur de provider	Fonctions de chat	Notes
OpenAI	'openai'	Oui	Fournisseur par défaut.
Anthropic	'anthropic'	Oui	Utilise le point de terminaison /v1/messages.

​

Observabilité

L’activité de la fonction d’IA est suivie via les ProfileEvents de ClickHouse :

ProfileEvent	Description
AIAPICalls	Nombre de requêtes HTTP envoyées au fournisseur d’IA.
AIInputTokens	Nombre total de tokens d’entrée consommés.
AIOutputTokens	Nombre total de tokens de sortie consommés.
AIRowsProcessed	Nombre de lignes ayant reçu un résultat.
AIRowsSkipped	Nombre de lignes ignorées (quota dépassé ou erreur avec ai_function_throw_on_error = 0).

Interrogez ces événements :

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

Introduit dans : v26.4.0

Classe le texte donné dans l’une des catégories fournies via un fournisseur de LLM.

La fonction envoie le texte avec une invite de classification fixe et un format de réponse basé sur un schéma JSON, qui contraint le modèle à renvoyer exactement l’un des libellés fournis. Lorsque la réponse est renvoyée sous la forme d’un objet JSON de la forme {"category": "..."}, le libellé est extrait et sa chaîne de caractères est renvoyée.

Le premier argument est une collection nommée qui spécifie le fournisseur, le modèle, le point de terminaison et, éventuellement, une clé API.

Syntaxe

aiClassify(collection, text, categories[, temperature])

Alias : AIClassify

Arguments

• collection — Nom d’une collection nommée contenant les identifiants du fournisseur et la configuration. String
• text — Texte à classifier. String
• categories — Liste constante des libellés des catégories candidates. Array(String)
• temperature — Température d’échantillonnage contrôlant l’aléa. Par défaut : 0.0. Float64

Valeur renvoyée

L’un des libellés de catégorie fournis, ou la valeur par défaut du type de colonne (chaîne vide) si la requête a échoué et que ai_function_throw_on_error est désactivé. String

Exemples

Classifier le sentiment

Query

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

Response

positive

Classifier une colonne

Query

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

Response

​

aiEmbed

Introduit dans : v26.6.0

Génère un vecteur d’embedding pour le texte donné à l’aide du fournisseur d’IA configuré.

La fonction envoie le texte au point de terminaison d’embedding configuré et renvoie le vecteur obtenu sous la forme Array(Float32). Au sein d’un même bloc de lignes, les entrées sont regroupées en lots de ai_function_embedding_max_batch_size entrées maximum par requête HTTP afin de réduire la surcharge de chaque appel.

Le premier argument est une collection nommée qui spécifie le fournisseur, le modèle, le point de terminaison et, éventuellement, une clé API. L’argument facultatif dimensions, lorsqu’il est pris en charge par le modèle (par exemple text-embedding-3-* d’OpenAI), demande un vecteur de la taille indiquée ; sinon, la taille native du modèle est renvoyée.

Syntaxe

aiEmbed(collection, text[, dimensions])

Arguments

• collection — Nom d’une collection nommée contenant les identifiants du fournisseur et la configuration. String
• text — Texte à encoder. String
• dimensions — Nombre de dimensions cible facultatif pour le vecteur de sortie. 0 ou l’omission de ce paramètre signifie utiliser la dimension native du modèle. UInt64

Valeur renvoyée

Le vecteur d’embedding, ou un tableau vide si l’entrée est NULL ou vide, si la requête a échoué et que ai_function_throw_on_error est désactivé, ou si un quota a été dépassé alors que ai_function_throw_on_quota_exceeded est désactivé. Array(Float32)

Exemples

Encoder une seule chaîne

Query

SELECT aiEmbed('ai_credentials', 'Hello world')

Response

Avec des dimensions explicites

Query

SELECT aiEmbed('ai_credentials', 'Hello world', 256)

Response

Intégrer une colonne de texte

Query

SELECT aiEmbed('ai_credentials', title, 256) FROM articles LIMIT 10

Response

​

aiExtract

Introduit dans : v26.4.0

Extrait des informations structurées à partir de texte non structuré à l’aide d’un fournisseur de LLM.

Le troisième argument peut être soit une instruction en langage naturel librement formulée (par ex. 'the main complaint'), soit un schéma au format JSON de la forme '{"field_a": "description of field a", "field_b": "description of field b"}'.

En mode instruction, la fonction renvoie la valeur extraite sous la forme d’une simple chaîne de caractères, ou une chaîne vide si rien n’a été trouvé. En mode schéma, la fonction renvoie une chaîne JSON représentant un objet dont les clés correspondent au schéma demandé ; les champs manquants sont null.

Le premier argument est une collection nommée qui spécifie le fournisseur, le modèle, le point de terminaison et, éventuellement, une clé API.

Syntaxe

aiExtract(collection, text, instruction_or_schema[, temperature])

Alias : AIExtract

Arguments

• collection — Nom d’une collection nommée contenant les identifiants du fournisseur et la configuration. String
• text — Texte à partir duquel extraire des informations. String
• instruction_or_schema — Instruction d’extraction en texte libre, ou objet JSON constant décrivant les champs à extraire. const String
• temperature — Température d’échantillonnage qui contrôle le caractère aléatoire. Par défaut : 0.0. const Float64

Valeur renvoyée

Une valeur extraite (mode instruction) ou une chaîne JSON représentant un objet (mode schéma). Renvoie la valeur par défaut du type de colonne (chaîne vide) si la requête a échoué et que ai_function_throw_on_error est désactivé. String

Exemples

Instruction en texte libre

Query

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

Response

late and damaged package

Extraction du schéma

Query

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

Response

​

aiGenerate

Introduite dans : v26.4.0

Génère du texte libre à partir d’un prompt à l’aide d’un fournisseur de LLM.

La fonction envoie le prompt au fournisseur d’IA configuré et renvoie le texte généré. Un system prompt facultatif peut être fourni pour guider le comportement du modèle (par exemple, le ton, le format ou le rôle). Si aucun system prompt n’est fourni, le system prompt par défaut est : You are a helpful assistant. Provide a clear and concise response.

Le premier argument est une collection nommée qui spécifie le fournisseur, le modèle, le point de terminaison et, éventuellement, une clé API.

Syntaxe

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

Alias : AIGenerate

Arguments

• collection — Nom d’une collection nommée contenant les identifiants du fournisseur et la configuration. String
• prompt — Le prompt ou la question de l’utilisateur à envoyer au modèle. String
• system_prompt — Instruction système constante facultative qui guide le comportement du modèle (par ex. persona, format de sortie) et est envoyée avec chaque prompt. String
• temperature — Température d’échantillonnage contrôlant le caractère aléatoire. Par défaut : 0.7. Float64

Valeur renvoyée

La réponse textuelle générée, ou la valeur par défaut du type de colonne (chaîne vide) si la requête a échoué et que ai_function_throw_on_error est désactivé. String

Exemples

Question simple

Query

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

Response

4

Avec le system prompt

Query

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

Response

Résumer les valeurs d’une colonne

Query

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

Response

​

aiTranslate

Introduit dans : v26.4.0

Traduit le texte donné vers la langue cible spécifiée à l’aide d’un fournisseur de LLM.

Des instructions supplémentaires de style ou de dialecte peuvent être passées comme quatrième argument (par ex. 'keep technical terms untranslated').

Le premier argument est une collection nommée qui spécifie le fournisseur, le modèle, le point de terminaison et, éventuellement, une clé API.

Syntaxe

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

Alias : AITranslate

Arguments

• collection — Nom d’une collection nommée contenant les identifiants du fournisseur et la configuration. String
• text — Texte à traduire. String
• target_language — Nom de la langue cible ou code BCP-47 (par exemple, 'French', 'es-MX'). String
• instructions — Instructions supplémentaires facultatives et constantes destinées au traducteur. String
• temperature — Température d’échantillonnage qui contrôle le caractère aléatoire. Valeur par défaut : 0.3. Float64

Valeur renvoyée

Le texte traduit, ou la valeur par défaut du type de la colonne (chaîne vide) si la requête a échoué et que ai_function_throw_on_error est désactivé. String

Exemples

Traduire en français

Query

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

Response

Bonjour le monde!

Traduire en japonais avec des consignes de style

Query

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

Response