Passer au contenu principal
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 :

​
Configuration

Les fonctions d’IA récupèrent les identifiants du fournisseur et la configuration à partir d’une collection nommée. Pour définir la collection nommée à utiliser pour les identifiants, utilisez le paramètre ai_function_credentials. Exemple d’instruction pour créer une collection nommée avec les identifiants du fournisseur : 
CREATE NAMED COLLECTION my_ai_credentials AS
    provider = 'openai',
    endpoint = 'https://api.openai.com/v1/chat/completions',
    model = 'gpt-4o-mini',
    api_key = 'sk-...';
Sélectionnez la collection avec le paramètre ai_function_credentials, pour la session ou pour une seule requête : 
-- 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';
Lorsqu’ai_function_credentials est vide (par défaut), une exception est levée.

​
Paramètres de la collection nommée

ParamètreTypePar défautDescription
providerString—Fournisseur du modèle. Valeurs prises en charge : 'openai', 'anthropic'. Voir la note ci-dessous.
endpointString—URL du point de terminaison de l’API.
modelString—Nom du modèle (par ex. 'gpt-4o-mini', 'text-embedding-3-small').
api_keyString—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_tokensUInt641024Nombre maximal de tokens de sortie par appel d’API.
api_versionString—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

Le choix de la collection nommée à utiliser est déterminé par le paramètre ai_function_credentials. Les autres paramètres liés à l’IA sont répertoriés dans Paramètres sous le préfixe ai_function_.

​
Utilisation dans les colonnes DEFAULT et MATERIALIZED

Le paramètre ai_function_credentials est lu au moment de l’évaluation de l’expression par défaut, et NON lors de la définition de la colonne. Le nom de la collection n’est pas stocké dans la définition de la colonne : 
CREATE TABLE t (id UInt32, doc String, vector Array(Float32) DEFAULT aiEmbed(doc)) ...;
-- The stored default is `aiEmbed(doc)`; no collection is captured.
L’évaluation de l’expression requiert trois éléments : allow_experimental_ai_functions et ai_function_credentials doivent être définis, et l’utilisateur qui l’évalue doit disposer de GRANT NAMED COLLECTION sur la collection nommée (la résolution des identifiants déclenche une vérification d’accès NAMED COLLECTION). Si l’un d’eux manque, une exception est levée (SUPPORT_IS_DISABLED, une erreur d’identifiants vides ou ACCESS_DENIED). Une colonne DEFAULT est évaluée au moment de l’INSERT, les deux paramètres doivent donc être définis dans la session ou la requête d’insertion : 
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');
Pour pouvoir insérer des données dans ces tables sans devoir définir ces deux paramètres pour chaque session, définissez-les tous les deux dans un profil de paramètres : 
<profiles>
    <default>
        <allow_experimental_ai_functions>1</allow_experimental_ai_functions>
        <ai_function_credentials>my_ai_credentials</ai_function_credentials>
    </default>
</profiles>
Une colonne MATERIALIZED est calculée lors d’un INSERT, comme une colonne DEFAULT, et elle est également recalculée par des mutations telles que ALTER TABLE ... MATERIALIZE COLUMN. Les mutations s’exécutent en dehors d’une session utilisateur et n’héritent pas de la clause SETTINGS d’une requête, mais elles héritent des paramètres d’un profil de paramètres. Définissez les deux paramètres dans un profil de paramètres et accordez le privilège NAMED COLLECTION au propriétaire de la table pour que le recalcul déclenché par une mutation puisse aboutir.

​
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

Fournisseurvaleur de providerFonctions de chatNotes
OpenAI'openai'OuiFournisseur par défaut.
Anthropic'anthropic'OuiUtilise le point de terminaison /v1/messages.

​
Observabilité

L’activité de la fonction d’IA est suivie via les ProfileEvents de ClickHouse :
ProfileEventDescription
AIAPICallsNombre de requêtes HTTP envoyées au fournisseur d’IA.
AIInputTokensNombre total de tokens d’entrée consommés.
AIOutputTokensNombre total de tokens de sortie consommés.
AIRowsProcessedNombre de lignes ayant reçu un résultat.
AIRowsSkippedNombre 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. Les identifiants du fournisseur et la configuration sont récupérés à partir de la collection nommée spécifiée par le paramètre ai_function_credentials. Syntaxe 
aiClassify(text, categories[, temperature])
Alias : AIClassify Arguments
  • 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('I love this product!', ['positive', 'negative', 'neutral']) SETTINGS ai_function_credentials = 'my_ai_credentials'
Response
positive
Classifier une colonne
Query
SELECT body, aiClassify(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. Les identifiants du fournisseur et la configuration sont récupérés à partir de la collection nommée spécifiée par le paramètre ai_function_credentials. 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(text[, dimensions])
Arguments
  • 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('Hello world') SETTINGS ai_function_credentials = 'my_ai_credentials'
Response
Avec des dimensions explicites
Query
SELECT aiEmbed('Hello world', 256) SETTINGS ai_function_credentials = 'my_ai_credentials'
Response
Intégrer une colonne de texte
Query
SELECT aiEmbed(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 deuxiè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. L’identifiant du fournisseur et la configuration proviennent de la collection nommée spécifiée par le paramètre ai_function_credentials. Syntaxe 
aiExtract(text, instruction_or_schema[, temperature])
Alias : AIExtract Arguments
  • 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('The package arrived late and was damaged.', 'the main complaint') SETTINGS ai_function_credentials = 'my_ai_credentials'
Response
late and damaged package
Extraction du schéma
Query
SELECT aiExtract(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. Les identifiants du fournisseur et la configuration sont extraits de la collection nommée spécifiée par le paramètre ai_function_credentials. Syntaxe 
aiGenerate(prompt[, system_prompt[, temperature]])
Alias : AIGenerate Arguments
  • 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('What is 2 + 2? Reply with just the number.') SETTINGS ai_function_credentials = 'my_ai_credentials'
Response
4
Avec le system prompt
Query
SELECT aiGenerate('Explain ClickHouse', 'You are a database expert. Be concise.') SETTINGS ai_function_credentials = 'my_ai_credentials'
Response
Résumer les valeurs d’une colonne
Query
SELECT article_title, aiGenerate(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 troisième argument (par ex. 'keep technical terms untranslated'). L’identifiant du fournisseur et la configuration sont récupérés à partir de la collection nommée spécifiée par le paramètre ai_function_credentials. Syntaxe 
aiTranslate(text, target_language[, instructions[, temperature]])
Alias : AITranslate Arguments
  • 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('Hello, world!', 'French') SETTINGS ai_function_credentials = 'my_ai_credentials'
Response
Bonjour le monde!
Traduire en japonais avec des consignes de style
Query
SELECT aiTranslate(body, 'Japanese', 'Use polite form (desu/masu)') FROM articles LIMIT 5
Response
Dernière modification le 25 juin 2026