> ## Documentation Index > Fetch the complete documentation index at: https://private-7c7dfe99-locadex-parallel-t9n-main-irpovz79o3kkpgs4.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_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`](/fr/reference/settings/session-settings#ai_function_max_input_tokens_per_query), [`ai_function_max_output_tokens_per_query`](/fr/reference/settings/session-settings#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_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_max_retries)) avec un backoff exponentiel ([`ai_function_retry_initial_delay_ms`](/fr/reference/settings/session-settings#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 : ```sql theme={null} 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](/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_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.
## 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; ``` {/*AUTOGENERATED_START*/}
## 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** ```sql theme={null} aiClassify(collection, text, categories[, temperature]) ``` **Alias** : `AIClassify` **Arguments** * `collection` — Nom d’une collection nommée contenant les identifiants du fournisseur et la configuration. [`String`](/fr/reference/data-types/string) * `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) * `temperature` — Température d’échantillonnage contrôlant l’aléa. Par défaut : `0.0`. [`Float64`](/fr/reference/data-types/float) **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('ai_credentials', 'I love this product!', ['positive', 'negative', 'neutral']) ``` ```response title=Response theme={null} positive ``` **Classifier une colonne** ```sql title=Query theme={null} SELECT body, aiClassify('ai_credentials', body, ['bug', 'question', 'feature']) AS kind FROM issues LIMIT 5 ``` ```response title=Response theme={null} ```
## 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`](/fr/reference/settings/session-settings#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** ```sql theme={null} aiEmbed(collection, text[, dimensions]) ``` **Arguments** * `collection` — Nom d’une collection nommée contenant les identifiants du fournisseur et la configuration. [`String`](/fr/reference/data-types/string) * `text` — Texte à encoder. [`String`](/fr/reference/data-types/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`](/fr/reference/data-types/int-uint) **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)`](/fr/reference/data-types/array) **Exemples** **Encoder une seule chaîne** ```sql title=Query theme={null} SELECT aiEmbed('ai_credentials', 'Hello world') ``` ```response title=Response theme={null} ``` **Avec des dimensions explicites** ```sql title=Query theme={null} SELECT aiEmbed('ai_credentials', 'Hello world', 256) ``` ```response title=Response theme={null} ``` **Intégrer une colonne de texte** ```sql title=Query theme={null} SELECT aiEmbed('ai_credentials', title, 256) FROM articles LIMIT 10 ``` ```response title=Response theme={null} ```
## 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** ```sql theme={null} 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`](/fr/reference/data-types/string) * `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) * `temperature` — Température d’échantillonnage qui contrôle le caractère aléatoire. Par défaut : `0.0`. [`const Float64`](/fr/reference/data-types/float) **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('ai_credentials', '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('ai_credentials', review, '{"sentiment": "positive, negative or neutral", "topic": "main topic of the review"}') FROM reviews LIMIT 5 ``` ```response title=Response theme={null} ```
## 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** ```sql theme={null} 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`](/fr/reference/data-types/string) * `prompt` — Le prompt ou la question de l’utilisateur à envoyer au modèle. [`String`](/fr/reference/data-types/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`](/fr/reference/data-types/string) * `temperature` — Température d’échantillonnage contrôlant le caractère aléatoire. Par défaut : `0.7`. [`Float64`](/fr/reference/data-types/float) **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`](/fr/reference/data-types/string) **Exemples** **Question simple** ```sql title=Query theme={null} SELECT aiGenerate('ai_credentials', 'What is 2 + 2? Reply with just the number.') ``` ```response title=Response theme={null} 4 ``` **Avec le system prompt** ```sql title=Query theme={null} SELECT aiGenerate('ai_credentials', 'Explain ClickHouse', 'You are a database expert. Be concise.') ``` ```response title=Response theme={null} ``` **Résumer les valeurs d’une colonne** ```sql title=Query theme={null} SELECT article_title, aiGenerate('ai_credentials', concat('Summarize in one sentence: ', article_body)) AS summary FROM articles LIMIT 5 ``` ```response title=Response theme={null} ```
## 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** ```sql theme={null} 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`](/fr/reference/data-types/string) * `text` — Texte à traduire. [`String`](/fr/reference/data-types/string) * `target_language` — Nom de la langue cible ou code BCP-47 (par exemple, `'French'`, `'es-MX'`). [`String`](/fr/reference/data-types/string) * `instructions` — Instructions supplémentaires facultatives et constantes destinées au traducteur. [`String`](/fr/reference/data-types/string) * `temperature` — Température d’échantillonnage qui contrôle le caractère aléatoire. Valeur par défaut : `0.3`. [`Float64`](/fr/reference/data-types/float) **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`](/fr/reference/data-types/string) **Exemples** **Traduire en français** ```sql title=Query theme={null} SELECT aiTranslate('ai_credentials', 'Hello, world!', 'French') ``` ```response title=Response theme={null} Bonjour le monde! ``` **Traduire en japonais avec des consignes de style** ```sql title=Query theme={null} SELECT aiTranslate('ai_credentials', body, 'Japanese', 'Use polite form (desu/masu)') FROM articles LIMIT 5 ``` ```response title=Response theme={null} ```