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.

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

Les fonctions d’IA s’appuient sur une collection nommée qui stocke les identifiants du fournisseur et la configuration. Différentes collections nommées peuvent être créées et utilisées pour différentes fonctions ou différents appels de fonction. Par exemple, vous pouvez définir une collection nommée distincte pour les fonctions de texte (aiGenerate, aiClassify, aiFilter, aiExtract, aiTranslate, aiRedact), et une autre pour les fonctions d’embedding (aiEmbed, aiSimilarity), qui nécessitent des points de terminaison différents et utilisent généralement des modèles différents.

Exemple d’instruction pour créer une collection nommée avec les identifiants du fournisseur, l’une avec un point de terminaison de chat et l’autre avec un point de terminaison d’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-...';

-- The embedding functions (`aiEmbed`, `aiSimilarity`) do not read `model` from the named collection,
-- pass it as a positional argument instead. Defining `model` in an embedding 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-...';

Une fonction détermine la collection nommée à utiliser dans l’ordre suivant :

1. la clé credentials de sa map de paramètres, lorsqu’elle est présente ;
2. sinon, le paramètre d’identifiant par défaut applicable :
   • ai_function_text_default_credentials pour les fonctions de texte (aiGenerate, aiClassify, aiFilter, aiExtract, aiTranslate, aiRedact) ;
   • ai_function_embedding_default_credentials pour les fonctions d’embedding (aiEmbed, aiSimilarity).

Si aucun des deux n’est défini, l’appel échoue. Les fonctions de texte et d’embedding utilisent des paramètres par défaut distincts, car un point de terminaison de chat-completions diffère de celui des 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'));

Filtrez les lignes à l’aide d’une condition en langage naturel avec aiFilter, qui renvoie un UInt8 et peut être utilisée directement dans WHERE :

SELECT * FROM reviews
WHERE aiFilter(body, 'the customer is angry about shipping');

Chaque fonction accepte, en dernier argument optionnel, une Map(String, String) de paramètres. Toutes les valeurs sont des chaînes de caractères (mettez les nombres entre apostrophes, par ex. '0.2'). Les clés inconnues sont rejetées. Une clé présente remplace la valeur correspondante de la collection nommée ; une clé absente se rabat sur la collection nommée (pour model/max_tokens) ou sur la valeur par défaut intégrée. Les exceptions sont les fonctions d’embedding (aiEmbed, aiSimilarity), qui prennent model comme argument positionnel obligatoire (par ex. aiEmbed(text, model[, params]), aiSimilarity(text1, text2, model[, params])) et renvoient une erreur si celui-ci est défini à la place dans la map de paramètres ou la collection nommée. Cela permet de garantir des embeddings reproductibles.

Les paramètres suivants sont communs à toutes les fonctions d’IA :

Certaines fonctions acceptent des paramètres supplémentaires qui leur sont propres (tels que max_tokens, temperature, system_prompt, instructions et dimensions). Consultez la référence de chaque fonction ci-dessous pour connaître les paramètres qu’elle accepte ainsi que leurs valeurs par défaut.

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

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

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.

Le transport est déterminé uniquement par le schéma de l’URL endpoint. Il n’existe aucun chiffrement du corps de la requête au niveau de l’application ; la protection des données en transit dépend entièrement du schéma :

• https:// — la connexion utilise TLS. Le corps de la requête (texte d’entrée, prompts) et l’api_key dans les en-têtes de la requête sont chiffrés en transit, et le certificat du fournisseur est validé. Utilisez cette option pour tout fournisseur distant.
• http:// — la connexion n’est pas chiffrée. Le corps de la requête et l’api_key sont envoyés en clair. Utilisez cette option uniquement pour un fournisseur de confiance sur un réseau privé (par exemple, une instance locale vLLM ou Ollama).

Par défaut, les fonctions d’IA rejettent un endpoint qui enverrait des données en clair à un hôte distant : tout point de terminaison non HTTPS dont l’hôte n’est pas une adresse de bouclage lève une exception. Les hôtes de bouclage (localhost, 127.0.0.0/8, ::1) sont exemptés, de sorte qu’un serveur de modèle local http://localhost fonctionne immédiatement. Pour autoriser un point de terminaison http:// en clair sur un hôte distant, définissez ai_function_allow_insecure_endpoint sur 1. Cette vérification est indépendante de remote_url_allow_hosts : ce paramètre est une liste d’hôtes autorisés et n’inspecte pas le schéma de l’URL, si bien qu’un point de terminaison http:// pointant vers un hôte autorisé est quand même accepté.

Notez que, dans les deux cas, le fournisseur reçoit les données d’entrée en clair après la terminaison TLS ; TLS protège les données uniquement sur le trajet réseau entre le serveur et le fournisseur.

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

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;

Introduit dans : v26.4.0

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

Les identifiants (une collection nommée spécifiant le fournisseur, le modèle, le point de terminaison et, éventuellement, une clé API) sont récupérés depuis la clé credentials de la map de paramètres optionnelle, ou depuis le paramètre ai_function_text_default_credentials lorsque la map l’omet.

Syntaxe

aiClassify(text, categories[, params])

Alias : AIClassify

Arguments

• text — Texte à classifier. String
• categories — Liste constante des libellés des catégories candidates. Array(String)
• params — Map(String, String) constant facultatif contenant des paramètres. Clés spécifiques à la fonction : temperature (température d’échantillonnage contrôlant l’aléa ; par défaut 0.0), max_tokens (nombre maximal de tokens de sortie par appel ; par défaut 1024). Les paramètres communs credentials et model s’appliquent également (voir Fonctions d’IA). Map(String, String)

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

SET allow_experimental_ai_functions = 1;
SELECT aiClassify('I love this product!', ['positive', 'negative', 'neutral'])

positive

Classifier une colonne avec des identifiants explicites

SET allow_experimental_ai_functions = 1;
CREATE TABLE issues (body String) ENGINE = Memory;
INSERT INTO issues VALUES ('The application exits unexpectedly after login.');
SELECT body, aiClassify(body, ['bug', 'question', 'feature'], map('credentials', 'ai_text_credentials')) AS kind FROM issues LIMIT 5

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). Dans un même block de rows, les entrées sont regroupées en batches de ai_function_embedding_max_batch_size entrées maximum par requête HTTP afin de réduire le surcoût de chaque appel.

Les identifiants (une collection nommée indiquant le fournisseur, le point de terminaison et, éventuellement, une clé API) sont récupérées à partir de la clé credentials de la map de paramètres, ou du paramètre ai_function_embedding_default_credentials lorsque la map ne la contient pas. Notez que aiEmbed utilise un paramètre d’identifiant par défaut distinct de celui des fonctions de texte, car un point de terminaison d’embeddings diffère d’un point de terminaison de chat.

Le model est un argument positionnel obligatoire (un String constant). Contrairement aux fonctions de texte, aiEmbed ne lit pas model à partir de la collection nommée ni de la map de paramètres. Une collection nommée qui définit model est rejetée.

Le paramètre facultatif dimensions, lorsqu’il est pris en charge par le modèle (par exemple les 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, model[, params])

Alias : AIEmbed

Arguments

• text — Texte à encoder. String
• model — Nom du modèle d’embedding. const String
• params — Map(String, String) constante facultative de paramètres. Clé propre à la fonction : dimensions (dimension cible du vecteur de sortie ; 0 ou l’absence de valeur signifie la taille native du modèle). Le paramètre commun credentials s’applique également (voir Fonctions d’IA). Map(String, String)

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é et que ai_function_throw_on_quota_exceeded est désactivé. Array(Float32)

Exemples

Encoder une seule chaîne (credentials peut être omis si le paramètre ai_function_embedding_default_credentials est défini)

SET allow_experimental_ai_functions = 1;
SELECT aiEmbed('Hello world', 'text-embedding-3-small', map('credentials', 'ai_embedding_credentials'))

Avec des dimensions explicites

SET allow_experimental_ai_functions = 1;
SELECT aiEmbed('Hello world', 'text-embedding-3-small', map('credentials', 'ai_embedding_credentials', 'dimensions', '256'))

Générer des embeddings pour une colonne de textes

SET allow_experimental_ai_functions = 1;
CREATE TABLE articles (title String) ENGINE = Memory;
INSERT INTO articles VALUES ('ClickHouse is a fast analytical database.');
SELECT aiEmbed(title, 'text-embedding-3-small', map('credentials', 'ai_embedding_credentials', 'dimensions', '256')) FROM articles LIMIT 10

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.

Les identifiants (une collection nommée qui spécifie le fournisseur, le modèle, le point de terminaison et, éventuellement, une clé API) sont pris dans la clé credentials de la map de paramètres facultative, ou dans le paramètre ai_function_text_default_credentials lorsque la map l’omet.

Syntaxe

aiExtract(text, instruction_or_schema[, params])

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
• params — Map(String, String) constant optionnel de paramètres. Clés spécifiques à la fonction : temperature (température d’échantillonnage qui contrôle le caractère aléatoire ; valeur par défaut : 0.0), max_tokens (nombre maximal de tokens de sortie par appel ; valeur par défaut : 1024). Les paramètres communs credentials et model s’appliquent également (voir Fonctions d’IA). Map(String, String)

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

SET allow_experimental_ai_functions = 1;
SELECT aiExtract('The package arrived late and was damaged.', 'the main complaint')

late and damaged package

Extraction du schéma

SET allow_experimental_ai_functions = 1;
CREATE TABLE reviews (review String) ENGINE = Memory;
INSERT INTO reviews VALUES ('The screen is bright, but the battery lasts only two hours.');
SELECT aiExtract(review, '{"sentiment": "positive, negative or neutral", "topic": "main topic of the review"}') FROM reviews LIMIT 5

Introduit dans : v26.8.0

Évalue une condition en langage naturel sur le texte fourni à l’aide d’un fournisseur de LLM et renvoie une valeur booléenne (UInt8) utilisable dans WHERE, PREWHERE et JOIN ... ON.

La fonction demande au modèle de répondre uniquement par true ou false en minuscules. Toute réponse complète autre que true (y compris false et le texte non reconnu) est mappée sur 0, de sorte que la ligne est filtrée. Une réponse incomplète signalée par le fournisseur — tronquée, filtrée par le contenu ou nécessitant une action supplémentaire — est en revanche traitée comme une erreur : lorsque ai_function_throw_on_error est activé (valeur par défaut), la requête est abandonnée ; lorsqu’il est désactivé, la ligne est mappée sur 0 et filtrée.

Avertissement : Ne vous fiez pas aux résultats d’aiFilter sans les examiner attentivement. Les prédicats basés sur des LLM peuvent être incorrects ou incohérents ; utilisez-les uniquement lorsque les faux positifs et les faux négatifs sont acceptables.

Les identifiants (une collection nommée spécifiant le fournisseur, le modèle, le point de terminaison et, éventuellement, une clé API) sont extraits de la clé credentials de la map de paramètres facultative ou du paramètre ai_function_text_default_credentials lorsque la map ne la contient pas.

Remarque : l’utilisation d’aiFilter dans JOIN ... ON évalue le LLM une fois par paire candidate et peut être coûteuse.

Syntaxe

aiFilter(text, condition[, params])

Alias : AIFilter

Arguments

• text — Texte à évaluer. String
• condition — Condition constante, exprimée en langage naturel, à laquelle le texte doit répondre. String
• params — Map(String, String) constant facultatif de paramètres. Clés propres à la fonction : temperature (température d’échantillonnage contrôlant l’aléa ; valeur par défaut : 0.0), max_tokens (nombre maximal de tokens de sortie par appel ; valeur par défaut : 1024). Les paramètres communs credentials et model s’appliquent également (voir Fonctions d’IA). Map(String, String)

Valeur renvoyée

1 si le texte répond à la condition, 0 sinon. Renvoie la valeur par défaut (0) si la requête échoue et que ai_function_throw_on_error est désactivé. UInt8

Exemples

Filtrer les avis négatifs

SET allow_experimental_ai_functions = 1;
CREATE TABLE reviews (body String) ENGINE = Memory;
INSERT INTO reviews VALUES ('The package arrived three days late.');
SELECT * FROM reviews WHERE aiFilter(body, 'the customer is angry about shipping')

Filtrer une colonne avec des identifiants explicites

SET allow_experimental_ai_functions = 1;
CREATE TABLE issues (body String) ENGINE = Memory;
INSERT INTO issues VALUES ('The application exits unexpectedly after login.');
SELECT body, aiFilter(body, 'describes a bug', map('credentials', 'ai_text_credentials')) AS is_bug FROM issues LIMIT 5

Introduit dans : v26.4.0

Génère du contenu textuel 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é.

Les identifiants (une collection nommée qui spécifie le fournisseur, le modèle, le point de terminaison et, éventuellement, une clé API) sont extraites de la clé credentials de la map de paramètres facultative, ou du paramètre ai_function_text_default_credentials lorsque la map ne la contient pas.

La map de paramètres facultative peut également définir system_prompt (une instruction qui guide le comportement du modèle, par ex. le ton, le format ou le rôle), temperature, max_tokens et model. Si system_prompt n’est pas défini, la valeur par défaut est : You are a helpful assistant. Provide a clear and concise response.

Syntaxe

aiGenerate(prompt[, params])

Alias : AIGenerate

Arguments

• prompt — Le prompt ou la question de l’utilisateur à envoyer au modèle. String
• params — Map(String, String) constant facultatif de paramètres. Clés propres à la fonction : temperature (température d’échantillonnage qui contrôle l’aléa ; valeur par défaut : 0.7), max_tokens (nombre maximal de tokens de sortie par appel ; valeur par défaut : 1024), system_prompt (instruction système constante guidant le comportement du modèle ; valeur par défaut : un prompt d’assistant générique). Les paramètres communs credentials et model s’appliquent également (voir Fonctions d’IA). Map(String, String)

Valeur renvoyée

Le texte généré, 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

SET allow_experimental_ai_functions = 1;
SELECT aiGenerate('What is 2 + 2? Reply with just the number.')

4

Avec des identifiants explicites et une instruction système

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

Résumer les valeurs d’une colonne

SET allow_experimental_ai_functions = 1;
CREATE TABLE articles (article_title String, article_body String) ENGINE = Memory;
INSERT INTO articles VALUES ('ClickHouse', 'ClickHouse is an open-source column-oriented database for online analytical processing.');
SELECT article_title, aiGenerate(concat('Summarize in one sentence: ', article_body)) AS summary FROM articles LIMIT 5

Introduite dans : v26.8.0

Détecte et masque les informations personnelles identifiables (PII) dans le texte fourni à l’aide d’un fournisseur de LLM.

Chaque occurrence de PII détectée est remplacée par un jeton de masquage ([REDACTED] par défaut, configurable via le paramètre replacement). Le tableau categories limite les types de PII à masquer ; un tableau vide utilise un ensemble par défaut de catégories courantes (nom, e-mail, numéro de téléphone, adresse, carte de crédit, adresse IP).

aiRedact demande au modèle de modifier uniquement les occurrences de PII détectées, mais la préservation du texte environnant reste approximative : le modèle peut tout de même le modifier (voir l’avertissement ci-dessus). Les caractères de contrôle autres que la tabulation, le saut de ligne et le retour chariot sont également remplacés par des espaces avant la requête ; la sortie n’est donc pas identique octet pour octet aux entrées qui en contiennent.

Étant donné que aiRedact renvoie l’intégralité du texte d’entrée avec les PII remplacées, la sortie est environ aussi longue que l’entrée. Définissez max_tokens (valeur par défaut : 1024) sur une valeur supérieure à la longueur de l’entrée en tokens ; une réponse tronquée en raison d’une limite trop basse est rejetée avec AI_PROVIDER_RESPONSE_TRUNCATED (ou renvoie la valeur par défaut de la colonne lorsque ai_function_throw_on_error est désactivé) au lieu de renvoyer du texte partiellement masqué.

Syntaxe

aiRedact(text, categories[, params])

Alias : AIRedact

Arguments

• text — Texte à masquer. String
• categories — Liste constante de catégories d’informations personnelles identifiables à masquer (par ex. ['name', 'ssn', 'credit_card']). Un tableau vide utilise un ensemble par défaut de catégories courantes (nom, e-mail, numéro de téléphone, adresse, carte de crédit, adresse IP). Array(String)
• params — Map(String, String) constant facultatif de paramètres. Clés spécifiques à la fonction : temperature (température d’échantillonnage contrôlant le caractère aléatoire ; valeur par défaut : 0.0), max_tokens (nombre maximal de tokens de sortie par appel ; valeur par défaut : 1024 — comme aiRedact renvoie l’intégralité du texte, définissez cette valeur au-dessus de la longueur de l’entrée en tokens ; une réponse tronquée en raison d’une limite trop basse est rejetée plutôt que de renvoyer du texte partiellement masqué), replacement (jeton qui remplace chaque occurrence de PII détectée ; valeur par défaut : [REDACTED]). Les paramètres communs credentials et model s’appliquent également (voir Fonctions d’IA). Map(String, String)

Valeur renvoyée

Le texte dans lequel les informations personnelles identifiables détectées sont remplacées par le jeton de masquage, 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

Masquer des catégories spécifiques

SET allow_experimental_ai_functions = 1;
SELECT aiRedact('Purchase was done by customer John Doe with email test@test.org', ['email', 'credit_card', 'name'])

Purchase was done by customer [REDACTED] with email [REDACTED]

Masquez les catégories de PII par défaut à l’aide d’un token personnalisé

SET allow_experimental_ai_functions = 1;
CREATE TABLE tickets (body String) ENGINE = Memory;
INSERT INTO tickets VALUES ('Contact Jane Doe at jane@example.com.');
SELECT aiRedact(body, [], map('replacement', '***')) FROM tickets LIMIT 5

Introduite dans : v26.8.0

Calcule la similarité sémantique entre deux textes à l’aide du fournisseur d’embeddings configuré.

Calcule les embeddings vectoriels des deux textes et renvoie leur similarité cosinus. Un score de -1 est attribué à des vecteurs d’embedding opposés ; sur le plan sémantique, cela signifie que les textes dont les scores approchent -1 ont un sens opposé. Un score de 0 signifie que les vecteurs sont orthogonaux : ils ne sont pas liés sémantiquement. Enfin, un score de 1 signifie que les vecteurs d’embedding pointent dans la même direction ; les textes dont les scores approchent 1 ont un sens similaire. Il s’agit du complément de cosineDistance pour les mêmes embeddings (aiSimilarity = 1 - cosineDistance(embedding1, embedding2)).

Le batching, les identifiants et le paramètre dimensions sont identiques à ceux d’aiEmbed, y compris le paramètre d’identifiant par défaut ai_function_embedding_default_credentials.

Comme pour aiEmbed, model est un argument positionnel obligatoire (un String constant) et n’est pas lu depuis la collection nommée ni la map de paramètres.

Syntaxe

aiSimilarity(text1, text2, model[, params])

Alias : AISimilarity

Arguments

• text1 — Premier texte. String
• text2 — Deuxième texte. String
• model — Nom du modèle d’embedding. const String
• params — Map(String, String) constant facultatif de paramètres. Clé propre à la fonction : dimensions (dimension cible des embeddings ; 0 ou l’absence de valeur utilise la taille native du modèle). Le paramètre commun credentials s’applique également (voir Fonctions d’IA). Map(String, String)

Valeur renvoyée

La similarité cosinus dans [-1, 1], ou NULL si l’un des textes est NULL ou vide, si une requête d’embedding a échoué alors 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é. Nullable(Float32)

Exemples

Comparer deux chaînes (credentials peut être omis si le paramètre ai_function_embedding_default_credentials est défini)

SET allow_experimental_ai_functions = 1;
SELECT aiSimilarity('cat', 'kitten', 'text-embedding-3-small', map('credentials', 'ai_embedding_credentials'))

Classer les avis selon leur similarité avec une requête

SET allow_experimental_ai_functions = 1;
CREATE TABLE product_reviews (review String) ENGINE = Memory;
INSERT INTO product_reviews VALUES ('It works well under rain.');
SELECT review FROM product_reviews ORDER BY aiSimilarity(review, 'It works well under rain', 'text-embedding-3-small') DESC LIMIT 100

Déduplication sémantique via une auto-jointure

SET allow_experimental_ai_functions = 1;
CREATE TABLE docs (id UInt64, title String) ENGINE = Memory;
INSERT INTO docs VALUES (1, 'ClickHouse documentation'), (2, 'ClickHouse database guide');
SELECT a.id, b.id FROM docs a, docs b WHERE a.id < b.id AND aiSimilarity(a.title, b.title, 'text-embedding-3-small') > 0.9

Introduit dans : v26.4.0

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

Des instructions supplémentaires de style ou de dialecte peuvent être transmises via la clé instructions de la map de paramètres (par exemple, 'keep technical terms untranslated').

Les identifiants (une collection nommée spécifiant le fournisseur, le modèle, le point de terminaison et, éventuellement, une clé API) sont extraits de la clé credentials de la map de paramètres facultative, ou du paramètre ai_function_text_default_credentials lorsque la map ne la contient pas.

Syntaxe

aiTranslate(text, target_language[, params])

Alias : AITranslate

Arguments

• text — Texte à traduire. String
• target_language — Nom de la langue cible ou code BCP-47 (par ex. 'French', 'es-MX'). String
• params — Map(String, String) constant facultatif de paramètres. Clés propres à la fonction : temperature (température d’échantillonnage contrôlant l’aléa ; valeur par défaut : 0.3), max_tokens (nombre maximal de tokens de sortie par appel ; valeur par défaut : 1024), instructions (instructions supplémentaires de style ou de dialecte pour le traducteur). Les paramètres communs credentials et model s’appliquent également (voir Fonctions d’IA). Map(String, String)

Valeur renvoyée

Le texte traduit, 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

Traduire en français

SET allow_experimental_ai_functions = 1;
SELECT aiTranslate('Hello, world!', 'French')

Bonjour le monde!

Traduire en japonais en suivant les consignes de style

SET allow_experimental_ai_functions = 1;
CREATE TABLE articles (body String) ENGINE = Memory;
INSERT INTO articles VALUES ('ClickHouse processes analytical queries quickly.');
SELECT aiTranslate(body, 'Japanese', map('instructions', 'Use polite form (desu/masu)')) FROM articles LIMIT 5