> ## Documentation Index > Fetch the complete documentation index at: https://private-7c7dfe99-trino-dialect.mintlify.site/llms.txt > Use this file to discover all available pages before exploring further. > Documentation des fonctions d'IA # 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`](/fr/reference/settings/session-settings/allow-experimental#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. **Injection de prompt** Le texte d’entrée est envoyé au modèle et peut orienter sa sortie (injection de prompt). Le texte provenant de sources externes, non vérifiées ou non nettoyées peut contenir des instructions qui amènent le modèle à renvoyer du contenu contrôlé par un attaquant, à ignorer le format demandé ou à émettre des payloads malveillants. Considérez la sortie des fonctions d’IA comme non fiable : validez-la ou nettoyez-la avant de l’utiliser dans des étapes ultérieures, telles que la construction de SQL, de commandes shell, de requêtes supplémentaires ou de décisions de contrôle d’accè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`](/fr/reference/settings/session-settings/ai-function#ai_function_max_input_tokens_per_query), [`ai_function_max_output_tokens_per_query`](/fr/reference/settings/session-settings/ai-function#ai_function_max_output_tokens_per_query)) et sur les appels d’API ([`ai_function_max_api_calls_per_query`](/fr/reference/settings/session-settings/ai-function#ai_function_max_api_calls_per_query)). * **Nouvelle tentative avec backoff** : les échecs temporaires sont réessayés ([`ai_function_max_retries`](/fr/reference/settings/session-settings/ai-function#ai_function_max_retries)) avec un backoff exponentiel ([`ai_function_retry_initial_delay_ms`](/fr/reference/settings/session-settings/ai-function#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. 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 : ```sql theme={null} 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-...'; ```
### 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'`). Utilisé par les fonctions de texte ; les fonctions d’embedding (`aiEmbed`, `aiSimilarity`) nécessitent `model` comme argument positionnel et génèrent une erreur si `model` est spécifié dans la collection nommée. | | `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.
### Sélection des identifiants
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`](/fr/reference/settings/session-settings/ai-function#ai_function_text_default_credentials) pour les fonctions de texte (`aiGenerate`, `aiClassify`, `aiFilter`, `aiExtract`, `aiTranslate`, `aiRedact`) ; * [`ai_function_embedding_default_credentials`](/fr/reference/settings/session-settings/ai-function#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. ```sql theme={null} 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` : ```sql theme={null} SELECT * FROM reviews WHERE aiFilter(body, 'the customer is angry about shipping'); ```
### Map de paramètres
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 : | Clé | Description | | ------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `credentials` | Collection nommée à utiliser (voir ci-dessus). | | `model` | Remplace le `model` de la collection (fonctions de texte uniquement ; les fonctions d’embedding (`aiEmbed`, `aiSimilarity`) prennent `model` comme argument positionnel obligatoire, pas comme clé de map). | 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. ```sql theme={null} SELECT aiGenerate(body, map('temperature', '0.2', 'system_prompt', 'You are terse.')) FROM articles; ```
### Paramètres au niveau de la requête
Tous les paramètres liés à l’IA sont répertoriés dans [Paramètres](/fr/reference/settings/session-settings) 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`](/fr/reference/settings/server-settings/settings/remote#remote_url_allow_hosts) dans la configuration du serveur, par exemple : ```xml theme={null} api.openai.com api.anthropic.com ``` Notez que ce paramètre s’applique à l’ensemble du serveur et à toutes les fonctionnalités utilisant HTTP.
### Sécurité du transport (HTTP vs HTTPS)
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`](/fr/reference/settings/session-settings/ai-function#ai_function_allow_insecure_endpoint) sur `1`. Cette vérification est indépendante de [`remote_url_allow_hosts`](/fr/reference/settings/server-settings/settings/remote#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.
## 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](/fr/reference/system-tables/query_log) 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 : ```sql theme={null} 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. 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** ```sql theme={null} aiClassify(text, categories[, params]) ``` **Alias** : `AIClassify` **Arguments** * `text` — Texte à classifier. [`String`](/fr/reference/data-types/string) * `categories` — Liste constante des libellés des catégories candidates. [`Array(String)`](/fr/reference/data-types/array) * `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](/fr/reference/functions/regular-functions/ai-functions)). [`Map(String, String)`](/fr/reference/data-types/map) **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`](/fr/reference/data-types/string) **Exemples** **Classifier le sentiment** ```sql title=Query theme={null} SELECT aiClassify('I love this product!', ['positive', 'negative', 'neutral']) ``` ```response title=Response theme={null} positive ``` **Classifier une colonne avec des informations d’identification explicites** ```sql title=Query theme={null} SELECT body, aiClassify(body, ['bug', 'question', 'feature'], map('credentials', 'ai_text_credentials')) AS kind FROM issues LIMIT 5 ```
## 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)`. Dans un même block de rows, les entrées sont regroupées en batches de [`ai_function_embedding_max_batch_size`](/fr/reference/settings/session-settings/ai-function#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** ```sql theme={null} aiEmbed(text, model[, params]) ``` **Alias** : `AIEmbed` **Arguments** * `text` — Texte à encoder. [`String`](/fr/reference/data-types/string) * `model` — Nom du modèle d’embedding. [`const String`](/fr/reference/data-types/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](/fr/reference/functions/regular-functions/ai-functions)). [`Map(String, String)`](/fr/reference/data-types/map) **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)`](/fr/reference/data-types/array) **Exemples** **Encoder une seule chaîne (`credentials` peut être omis si le paramètre `ai_function_embedding_default_credentials` est défini)** ```sql title=Query theme={null} SELECT aiEmbed('Hello world', 'text-embedding-3-small', map('credentials', 'ai_embedding_credentials')) ``` **Avec des dimensions explicites** ```sql title=Query theme={null} 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** ```sql title=Query theme={null} SELECT aiEmbed(title, 'text-embedding-3-small', map('credentials', 'ai_embedding_credentials', 'dimensions', '256')) FROM articles LIMIT 10 ```
## 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`. 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** ```sql theme={null} aiExtract(text, instruction_or_schema[, params]) ``` **Alias** : `AIExtract` **Arguments** * `text` — Texte à partir duquel extraire des informations. [`String`](/fr/reference/data-types/string) * `instruction_or_schema` — Instruction d’extraction en texte libre, ou objet JSON constant décrivant les champs à extraire. [`const String`](/fr/reference/data-types/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](/fr/reference/functions/regular-functions/ai-functions)). [`Map(String, String)`](/fr/reference/data-types/map) **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`](/fr/reference/data-types/string) **Exemples** **Instruction en texte libre** ```sql title=Query theme={null} SELECT aiExtract('The package arrived late and was damaged.', 'the main complaint') ``` ```response title=Response theme={null} late and damaged package ``` **Extraction du schéma** ```sql title=Query theme={null} SELECT aiExtract(review, '{"sentiment": "positive, negative or neutral", "topic": "main topic of the review"}') FROM reviews LIMIT 5 ```
## aiFilter
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. Les requêtes échouées (lorsque `ai_function_throw_on_error` est désactivé) et les réponses non reconnues sont mappées sur `0`, de sorte que la ligne est 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** ```sql theme={null} aiFilter(text, condition[, params]) ``` **Alias** : `AIFilter` **Arguments** * `text` — Texte à évaluer. [`String`](/fr/reference/data-types/string) * `condition` — Condition constante, exprimée en langage naturel, à laquelle le texte doit répondre. [`String`](/fr/reference/data-types/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](/fr/reference/functions/regular-functions/ai-functions)). [`Map(String, String)`](/fr/reference/data-types/map) **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`](/fr/reference/data-types/int-uint) **Exemples** **Filtrer les avis négatifs** ```sql title=Query theme={null} SELECT * FROM reviews WHERE aiFilter(body, 'the customer is angry about shipping') ``` **Filtrer une colonne avec des identifiants explicites** ```sql title=Query theme={null} SELECT body, aiFilter(body, 'describes a bug', map('credentials', 'ai_text_credentials')) AS is_bug FROM issues LIMIT 5 ```
## aiGenerate
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 informations d’identifiant (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** ```sql theme={null} aiGenerate(prompt[, params]) ``` **Alias** : `AIGenerate` **Arguments** * `prompt` — Le prompt ou la question de l’utilisateur à envoyer au modèle. [`String`](/fr/reference/data-types/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](/fr/reference/functions/regular-functions/ai-functions)). [`Map(String, String)`](/fr/reference/data-types/map) **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`](/fr/reference/data-types/string) **Exemples** **Question simple** ```sql title=Query theme={null} SELECT aiGenerate('What is 2 + 2? Reply with just the number.') ``` ```response title=Response theme={null} 4 ``` **Avec des identifiants explicites et une instruction système** ```sql title=Query theme={null} 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** ```sql title=Query theme={null} SELECT article_title, aiGenerate(concat('Summarize in one sentence: ', article_body)) AS summary FROM articles LIMIT 5 ```
## aiRedact
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. `aiRedact` détecte et masque les PII au mieux à l’aide d’un LLM, mais sa sortie n’est pas fiable. La détection et la suppression des PII dépendent du modèle choisi, du prompt et de l’entrée : le modèle peut ne pas détecter certains identifiants, ne les masquer que partiellement ou modifier le texte environnant. Il fonctionne mieux avec du texte anglais bien rédigé ; les résultats peuvent être moins bons dans d’autres langues ou pour du texte comportant de nombreuses erreurs d’orthographe, de ponctuation ou de grammaire. `aiRedact` ne garantit pas que sa sortie est exempte de PII et ne doit pas être considéré, à lui seul, comme un mécanisme d’anonymisation sûr ou suffisant. Vérifiez toujours la sortie afin de vous assurer qu’elle respecte les politiques de confidentialité et de conformité des données de votre organisation avant d’exposer des données à des tiers non fiables. 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 sera incomplète. **Syntaxe** ```sql theme={null} aiRedact(text, categories[, params]) ``` **Alias** : `AIRedact` **Arguments** * `text` — Texte à masquer. [`String`](/fr/reference/data-types/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)`](/fr/reference/data-types/array) * `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, faute de quoi la réponse risque d’être tronquée et incomplète), `replacement` (jeton qui remplace chaque span d’informations personnelles identifiables détecté ; valeur par défaut : `[REDACTED]`). Les paramètres communs `credentials` et `model` s’appliquent également (voir [Fonctions d’IA](/fr/reference/functions/regular-functions/ai-functions)). [`Map(String, String)`](/fr/reference/data-types/map) **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`](/fr/reference/data-types/string) **Exemples** **Masquer des catégories spécifiques** ```sql title=Query theme={null} SELECT aiRedact('Purchase was done by customer John Doe with email test@test.org', ['email', 'credit_card', 'name']) ``` ```response title=Response theme={null} Purchase was done by customer [REDACTED] with email [REDACTED] ``` **Masquez les catégories d’IPI par défaut à l’aide d’un token personnalisé** ```sql title=Query theme={null} SELECT aiRedact(body, [], map('replacement', '***')) FROM tickets LIMIT 5 ```
## aiSimilarity
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](https://en.wikipedia.org/wiki/Cosine_similarity). 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** ```sql theme={null} aiSimilarity(text1, text2, model[, params]) ``` **Alias** : `AISimilarity` **Arguments** * `text1` — Premier texte. [`String`](/fr/reference/data-types/string) * `text2` — Deuxième texte. [`String`](/fr/reference/data-types/string) * `model` — Nom du modèle d’embedding. [`const String`](/fr/reference/data-types/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](/fr/reference/functions/regular-functions/ai-functions)). [`Map(String, String)`](/fr/reference/data-types/map) **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)`](/fr/reference/data-types/nullable) **Exemples** **Comparer deux chaînes (`credentials` peut être omis si le paramètre `ai_function_embedding_default_credentials` est défini)** ```sql title=Query theme={null} SELECT aiSimilarity('cat', 'kitten', 'text-embedding-3-small', map('credentials', 'ai_embedding_credentials')) ``` **Classer les avis selon leur similarité avec une requête** ```sql title=Query theme={null} 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** ```sql title=Query theme={null} 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 ```
## aiTranslate
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** ```sql theme={null} aiTranslate(text, target_language[, params]) ``` **Alias** : `AITranslate` **Arguments** * `text` — Texte à traduire. [`String`](/fr/reference/data-types/string) * `target_language` — Nom de la langue cible ou code BCP-47 (par ex. `'French'`, `'es-MX'`). [`String`](/fr/reference/data-types/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](/fr/reference/functions/regular-functions/ai-functions)). [`Map(String, String)`](/fr/reference/data-types/map) **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`](/fr/reference/data-types/string) **Exemples** **Traduire en français** ```sql title=Query theme={null} SELECT aiTranslate('Hello, world!', 'French') ``` ```response title=Response theme={null} Bonjour le monde! ``` **Traduire en japonais en suivant les consignes de style** ```sql title=Query theme={null} SELECT aiTranslate(body, 'Japanese', map('instructions', 'Use polite form (desu/masu)')) FROM articles LIMIT 5 ```