> ## Documentation Index > Fetch the complete documentation index at: https://clickhouse.com/docs/llms.txt > Use this file to discover all available pages before exploring further. > Документация по функциям ИИ # Функции ИИ Функции ИИ — это встроенные функции ClickHouse, которые можно использовать для вызова ИИ или генерации эмбеддингов при работе с данными, извлечении информации, классификации данных и т. д. Функции ИИ являются экспериментальными. Чтобы включить их, установите [`allow_experimental_ai_functions`](/docs/ru/reference/settings/session-settings#allow_experimental_ai_functions). Функции ИИ могут возвращать непредсказуемые результаты. Результат во многом зависит от качества промпта и используемой модели. Все функции используют общую инфраструктуру, которая обеспечивает: * **Контроль квот**: лимиты на количество токенов в рамках одного запроса ([`ai_function_max_input_tokens_per_query`](/docs/ru/reference/settings/session-settings#ai_function_max_input_tokens_per_query), [`ai_function_max_output_tokens_per_query`](/docs/ru/reference/settings/session-settings#ai_function_max_output_tokens_per_query)) и вызовов API ([`ai_function_max_api_calls_per_query`](/docs/ru/reference/settings/session-settings#ai_function_max_api_calls_per_query)). * **Повторные попытки с задержкой**: при временных сбоях выполняются повторные попытки ([`ai_function_max_retries`](/docs/ru/reference/settings/session-settings#ai_function_max_retries)) с экспоненциально растущей задержкой ([`ai_function_retry_initial_delay_ms`](/docs/ru/reference/settings/session-settings#ai_function_retry_initial_delay_ms)).
## Конфигурация
Функции ИИ используют **именованную коллекцию**, в которой хранятся учётные данные провайдера и параметры конфигурации. Для разных функций или их вызовов можно создавать и использовать разные именованные коллекции. Например, для текстовых функций (`aiGenerate`, `aiClassify`, `aiExtract`, `aiTranslate`) и функции `aiEmbed` можно определить отдельные именованные коллекции, так как им требуются разные конечные точки и обычно разные модели. Пример оператора для создания именованной коллекции с учётными данными провайдера: одна — с конечной точкой для чата, другая — с конечной точкой для эмбеддингов: ```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-...'; -- `aiEmbed` does not read `model` from the named collection; pass it as a positional argument instead. -- Defining `model` in an `aiEmbed` 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-...'; ```
### Параметры именованной коллекции
| Параметр | Тип | По умолчанию | Описание | | ------------- | ------ | ------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `provider` | String | — | Провайдер модели. Поддерживаются: `'openai'`, `'anthropic'`. См. примечание ниже. | | `endpoint` | String | — | URL конечной точки API. | | `model` | String | — | Имя модели (например, `'gpt-4o-mini'`). Используется текстовыми функциями; `aiEmbed` требует `model` в качестве позиционного аргумента и возвращает ошибку, если `model` указан в именованной коллекции. | | `api_key` | String | — | Ключ аутентификации для провайдера. Необязательно: если параметр не указан, заголовок аутентификации не отправляется, что позволяет использовать OpenAI-совместимые серверы, не требующие аутентификации. | | `max_tokens` | UInt64 | `1024` | Максимальное количество выходных токенов на один вызов API. | | `api_version` | String | — | Строка версии API. Используется в Anthropic (`'2023-06-01'`). | Любой API, совместимый с OpenAI (например, vLLM, Ollama, LiteLLM), можно использовать, если задать `provider = 'openai'` и указать в `endpoint` конечную точку вашего сервиса.
### Выбор учетных данных
Функция определяет именованную коллекцию, которую следует использовать, в следующем порядке: 1. ключ `credentials` из её карты параметров, если он указан; 2. в противном случае — соответствующую настройку учетных данных по умолчанию: * [`ai_function_text_default_credentials`](/docs/ru/reference/settings/session-settings#ai_function_text_default_credentials) для текстовых функций (`aiGenerate`, `aiClassify`, `aiExtract`, `aiTranslate`); * [`ai_function_embedding_default_credentials`](/docs/ru/reference/settings/session-settings#ai_function_embedding_default_credentials) для `aiEmbed`. Если не задано ни то ни другое, вызов завершится ошибкой. Для текстовых функций и функций эмбеддингов используются разные настройки по умолчанию, поскольку конечная точка для chat-completions отличается от конечной точки для эмбеддингов. ```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')); ```
### Карта параметров
Каждая функция принимает необязательный завершающий `Map(String, String)` с параметрами. Все значения — строки (числа заключайте в кавычки, например `'0.2'`). Неизвестные ключи отклоняются. Если ключ указан, он переопределяет соответствующее значение из именованной коллекции; если ключ отсутствует, используется значение из именованной коллекции (для `model`/`max_tokens`) или встроенное значение по умолчанию. Исключение — `aiEmbed`: в этой функции `model` передаётся как обязательный позиционный аргумент (`aiEmbed(text, model[, params])`), и если вместо этого задать его в карте параметров или именованной коллекции, возникнет ошибка. Следующие параметры являются общими для всех функций ИИ: | Key | Description | | ------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- | | `credentials` | Именованная коллекция для использования (см. выше). | | `model` | Переопределяет `model` коллекции (только для текстовых функций; в `aiEmbed` `model` передаётся как обязательный позиционный аргумент, а не как ключ карты). | Отдельные функции принимают дополнительные, специфичные для конкретной функции параметры (например, `max_tokens`, `temperature`, `system_prompt`, `instructions` и `dimensions`). Сведения о поддерживаемых параметрах и их значениях по умолчанию см. ниже в справочнике для каждой функции. ```sql theme={null} SELECT aiGenerate(body, map('temperature', '0.2', 'system_prompt', 'You are terse.')) FROM articles; ```
### Настройки на уровне запроса
Все настройки, связанные с ИИ, перечислены в разделе [Настройки](/docs/ru/reference/settings/session-settings) и имеют префикс `ai_function_`.
### Ограничение хостов конечных точек
URL `endpoint` в именованной коллекции AI — это исходящий пункт назначения, к которому сервер подключается от своего имени, потенциально передавая (если указан) `api_key` этой именованной коллекции в заголовках запроса. По умолчанию ClickHouse разрешает любой хост. Чтобы ограничить функции определённым набором провайдеров, настройте [`remote_url_allow_hosts`](/docs/ru/reference/settings/server-settings/settings#remote_url_allow_hosts) в конфигурации сервера, например: ```xml theme={null} api.openai.com api.anthropic.com ``` Обратите внимание, что этот параметр является общесерверным и применяется ко всем возможностям, использующим HTTP.
### Безопасность передачи данных (HTTP vs HTTPS)
Способ передачи определяется исключительно схемой URL `endpoint`. Шифрования полезной нагрузки запроса на уровне приложения нет; защита данных при передаче полностью зависит от схемы: * `https://` — соединение использует TLS. Тело запроса (входной текст, промпты) и `api_key` в заголовках запроса шифруются при передаче, а сертификат провайдера проверяется. Используйте этот вариант для любого удалённого провайдера. * `http://` — соединение **не шифруется**. Тело запроса и `api_key` передаются в открытом виде. Используйте этот вариант только для доверенного провайдера в частной сети (например, для локального экземпляра `vLLM` или `Ollama`). Функция ИИ не требует HTTPS принудительно: конечная точка `http://` принимается, и данные отправляются без шифрования. Сейчас нет настройки на стороне сервера, которая отклоняла бы незашифрованные конечные точки ИИ — [`remote_url_allow_hosts`](/docs/ru/reference/settings/server-settings/settings#remote_url_allow_hosts) ограничивает только хост пункта назначения и не проверяет схему URL, поэтому конечная точка `http://` на разрешённом хосте всё равно проходит. Чтобы гарантировать шифрование при передаче, настройте именованные коллекции с конечными точками `https://`. Обратите внимание: в обоих случаях провайдер получает входные данные в открытом виде после завершения TLS; TLS защищает данные только на сетевом участке между сервером и провайдером.
## Поддерживаемые провайдеры
| Провайдер | Значение `provider` | Функции чата | Примечания | | --------- | ------------------- | ------------ | ----------------------------------------- | | OpenAI | `'openai'` | Да | Провайдер по умолчанию. | | Anthropic | `'anthropic'` | Да | Использует конечную точку `/v1/messages`. |
## Обсервабилити
Активность функции ИИ отслеживается через ClickHouse [ProfileEvents](/docs/ru/reference/system-tables/query_log): | ProfileEvent | Description | | ----------------- | -------------------------------------------------------------------------------------------------------- | | `AIAPICalls` | Количество HTTP-запросов, отправленных провайдеру ИИ. | | `AIInputTokens` | Общее количество использованных входных токенов. | | `AIOutputTokens` | Общее количество использованных выходных токенов. | | `AIRowsProcessed` | Количество строк, для которых был получен результат. | | `AIRowsSkipped` | Количество пропущенных строк (превышена квота или возникла ошибка при `ai_function_throw_on_error = 0`). | Запросите эти события: ```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
Добавленный в: v26.4.0 Классифицирует заданный текст по одной из указанных категорий с помощью провайдера LLM. Функция отправляет текст вместе с фиксированным промптом для классификации и форматом ответа в виде JSON Schema, который ограничивает модель так, чтобы она возвращала ровно одну из переданных меток. Если ответ возвращается как объект JSON вида `{"category": "..."}`, метка извлекается, и функция возвращает строку этой метки. Учетные данные (именованная коллекция, задающая провайдера, модель, конечную точку и, при необходимости, ключ API) берутся из ключа `credentials` в необязательной карте параметров или из настройки `ai_function_text_default_credentials`, если в карте этот ключ отсутствует. **Синтаксис** ```sql theme={null} aiClassify(text, categories[, params]) ``` **Псевдонимы**: `AIClassify` **Аргументы** * `text` — Текст для классификации. [`String`](/docs/ru/reference/data-types/string) * `categories` — Константный список возможных меток категорий. [`Array(String)`](/docs/ru/reference/data-types/array) * `params` — Необязательный константный набор параметров `Map(String, String)`. Ключи, специфичные для функции: `temperature` (температура сэмплирования, влияющая на случайность; по умолчанию `0.0`), `max_tokens` (максимальное количество выходных токенов за один вызов; по умолчанию `1024`). Также применяются общие параметры `credentials` и `model` (см. [функции ИИ](/docs/ru/reference/functions/regular-functions/ai-functions)). [`Map(String, String)`](/docs/ru/reference/data-types/map) **Возвращаемое значение** Одна из указанных меток категорий или значение по умолчанию для типа столбца (пустая строка), если при запросе произошла ошибка и `ai_function_throw_on_error` отключен. [`String`](/docs/ru/reference/data-types/string) **Примеры** **Классификация тональности** ```sql title=Query theme={null} SELECT aiClassify('I love this product!', ['positive', 'negative', 'neutral']) ``` ```response title=Response theme={null} positive ``` **Классификация столбца с явно заданными учетными данными** ```sql title=Query theme={null} SELECT body, aiClassify(body, ['bug', 'question', 'feature'], map('credentials', 'ai_text_credentials')) AS kind FROM issues LIMIT 5 ```
## aiEmbed
Добавленный в: v26.6.0 Генерирует эмбеддинг-вектор для заданного текста с использованием настроенного ИИ-провайдера. Функция отправляет текст в настроенную конечную точку эмбеддингов и возвращает полученный вектор как `Array(Float32)`. В пределах одного блока строк входные данные группируются в батчи до [`ai_function_embedding_max_batch_size`](/docs/ru/reference/settings/session-settings#ai_function_embedding_max_batch_size) записей на один HTTP-запрос, чтобы сократить накладные расходы на каждый вызов. Учетные данные (именованная коллекция, задающая провайдера, конечную точку и, при необходимости, ключ API) берутся из ключа `credentials` карты параметров или из настройки `ai_function_embedding_default_credentials`, если в карте этот ключ отсутствует. Обратите внимание, что `aiEmbed` использует отдельную настройку учетных данных по умолчанию, отличную от той, что используется текстовыми функциями, поскольку конечная точка эмбеддингов отличается от конечной точки чата. `model` — обязательный позиционный аргумент (константный `String`). В отличие от текстовых функций, `aiEmbed` не считывает `model` из именованной коллекции или карты параметров. Именованная коллекция, в которой задан `model`, отклоняется, а не просто молча игнорируется. Необязательный параметр `dimensions`, если он поддерживается моделью (например, в OpenAI `text-embedding-3-*`), запрашивает вектор указанного размера; в противном случае возвращается собственная размерность модели. **Синтаксис** ```sql theme={null} aiEmbed(text, model[, params]) ``` **Аргументы** * `text` — Текст для получения эмбеддинга. [`String`](/docs/ru/reference/data-types/string) * `model` — Имя модели эмбеддингов. [`const String`](/docs/ru/reference/data-types/string) * `params` — Необязательная константа `Map(String, String)` с параметрами. Специфичный для функции ключ: `dimensions` (целевая размерность выходного вектора; `0` или отсутствие значения означает исходную размерность модели). Также применяется общий параметр `credentials` (см. [Функции ИИ](/docs/ru/reference/functions/regular-functions/ai-functions)). [`Map(String, String)`](/docs/ru/reference/data-types/map) **Возвращаемое значение** Эмбеддинг-вектор или пустой массив, если входное значение равно NULL или пусто, запрос завершился с ошибкой и `ai_function_throw_on_error` отключён, либо была превышена квота при отключённом `ai_function_throw_on_quota_exceeded`. [`Array(Float32)`](/docs/ru/reference/data-types/array) **Примеры** **Эмбеддинг одной строки (`credentials` можно опустить, если задана настройка `ai_function_embedding_default_credentials`)** ```sql title=Query theme={null} SELECT aiEmbed('Hello world', 'text-embedding-3-small', map('credentials', 'ai_embedding_credentials')) ``` **С явно заданной размерностью** ```sql title=Query theme={null} SELECT aiEmbed('Hello world', 'text-embedding-3-small', map('credentials', 'ai_embedding_credentials', 'dimensions', '256')) ``` **Вычислить эмбеддинги для столбца с текстами** ```sql title=Query theme={null} SELECT aiEmbed(title, 'text-embedding-3-small', map('credentials', 'ai_embedding_credentials', 'dimensions', '256')) FROM articles LIMIT 10 ```
## aiExtract
Добавленный в: v26.4.0 Извлекает структурированную информацию из неструктурированного текста с помощью провайдера LLM. Третий аргумент может быть либо произвольной инструкцией на естественном языке (например, `'the main complaint'`), либо JSON-кодированной схемой вида `'{"field_a": "description of field a", "field_b": "description of field b"}'`. В режиме инструкции функция возвращает извлечённое значение в виде обычной строки или пустую строку, если ничего не найдено. В режиме схемы функция возвращает строку с объектом JSON, ключи которого соответствуют запрошенной схеме; отсутствующие поля имеют значение `null`. Учетные данные (именованная коллекция, задающая провайдера, модель, конечную точку и, при необходимости, ключ API) берутся из ключа `credentials` необязательной карты параметров или из настройки `ai_function_text_default_credentials`, если в карте этот ключ отсутствует. **Синтаксис** ```sql theme={null} aiExtract(text, instruction_or_schema[, params]) ``` **Псевдонимы**: `AIExtract` **Аргументы** * `text` — Текст, из которого нужно извлечь информацию. [`String`](/docs/ru/reference/data-types/string) * `instruction_or_schema` — Инструкция для извлечения в свободной форме или константный объект JSON, описывающий извлекаемые поля. [`const String`](/docs/ru/reference/data-types/string) * `params` — Необязательный константный `Map(String, String)` параметров. Ключи, специфичные для функции: `temperature` (температура сэмплирования, определяющая степень случайности; по умолчанию `0.0`), `max_tokens` (максимальное количество выходных токенов на вызов; по умолчанию `1024`). Также применяются общие параметры `credentials` и `model` (см. [функции ИИ](/docs/ru/reference/functions/regular-functions/ai-functions)). [`Map(String, String)`](/docs/ru/reference/data-types/map) **Возвращаемое значение** Одно извлечённое значение (режим инструкции) или строка с объектом JSON (режим схемы). Возвращает значение по умолчанию для типа столбца (пустую строку), если запрос завершился ошибкой и `ai_function_throw_on_error` отключён. [`String`](/docs/ru/reference/data-types/string) **Примеры** **Инструкция в свободной форме** ```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 ``` **Извлечение схемы** ```sql title=Query theme={null} SELECT aiExtract(review, '{"sentiment": "positive, negative or neutral", "topic": "main topic of the review"}') FROM reviews LIMIT 5 ```
## aiGenerate
Добавленный в: v26.4.0 Генерирует произвольный текст по промпту с помощью провайдера LLM. Функция отправляет промпт настроенному AI-провайдеру и возвращает сгенерированный текст. Учетные данные (именованная коллекция с указанием провайдера, модели, конечной точки и, при необходимости, ключа API) берутся из ключа `credentials` необязательной карты параметров или из настройки `ai_function_text_default_credentials`, если этот ключ в карте отсутствует. Необязательная карта параметров также может задавать `system_prompt` (инструкцию, определяющую поведение модели, например тон, формат или роль), `temperature`, `max_tokens` и `model`. Если `system_prompt` не задан, по умолчанию используется: `You are a helpful assistant. Provide a clear and concise response.` **Синтаксис** ```sql theme={null} aiGenerate(prompt[, params]) ``` **Псевдонимы**: `AIGenerate` **Аргументы** * `prompt` — Пользовательский промпт или вопрос, отправляемый модели. [`String`](/docs/ru/reference/data-types/string) * `params` — Необязательный константный `Map(String, String)` с параметрами. Специфичные для функции ключи: `temperature` (температура сэмплирования, управляющая случайностью; по умолчанию `0.7`), `max_tokens` (максимальное число выходных токенов за один вызов; по умолчанию `1024`), `system_prompt` (константная системная инструкция, определяющая поведение модели; по умолчанию — общий промпт ассистента). Также применяются общие параметры `credentials` и `model` (см. [функции ИИ](/docs/ru/reference/functions/regular-functions/ai-functions)). [`Map(String, String)`](/docs/ru/reference/data-types/map) **Возвращаемое значение** Сгенерированный текстовый ответ или значение по умолчанию для типа столбца (пустая строка), если запрос завершился ошибкой и `ai_function_throw_on_error` отключён. [`String`](/docs/ru/reference/data-types/string) **Примеры** **Простой вопрос** ```sql title=Query theme={null} SELECT aiGenerate('What is 2 + 2? Reply with just the number.') ``` ```response title=Response theme={null} 4 ``` **С явными учетными данными и системным промптом** ```sql title=Query theme={null} SELECT aiGenerate('Explain ClickHouse', map('credentials', 'ai_text_credentials', 'system_prompt', 'You are a database expert. Be concise.')) ``` **Сводка значений столбца** ```sql title=Query theme={null} SELECT article_title, aiGenerate(concat('Summarize in one sentence: ', article_body)) AS summary FROM articles LIMIT 5 ```
## aiTranslate
Добавленный в: v26.4.0 Переводит заданный текст на указанный целевой язык с помощью провайдера LLM. Дополнительные указания по стилю или диалекту можно передать через ключ `instructions` в карте параметров (например, `'keep technical terms untranslated'`). Учетные данные (именованная коллекция, задающая провайдера, модель, конечную точку и, при необходимости, ключ API) берутся из ключа `credentials` необязательной карты параметров или из настройки `ai_function_text_default_credentials`, если в карте этот ключ отсутствует. **Синтаксис** ```sql theme={null} aiTranslate(text, target_language[, params]) ``` **Псевдонимы**: `AITranslate` **Аргументы** * `text` — Текст для перевода. [`String`](/docs/ru/reference/data-types/string) * `target_language` — Название целевого языка или код BCP-47 (например, `'French'`, `'es-MX'`). [`String`](/docs/ru/reference/data-types/string) * `params` — Необязательная константа `Map(String, String)` с параметрами. Ключи, специфичные для этой функции: `temperature` (температура сэмплирования, определяющая случайность; по умолчанию `0.3`), `max_tokens` (максимальное количество выходных токенов за один вызов; по умолчанию `1024`), `instructions` (дополнительные указания по стилю или диалекту для переводчика). Также применяются общие параметры `credentials` и `model` (см. [Функции ИИ](/docs/ru/reference/functions/regular-functions/ai-functions)). [`Map(String, String)`](/docs/ru/reference/data-types/map) **Возвращаемое значение** Переведённый текст или значение по умолчанию для типа столбца (пустая строка), если запрос завершился ошибкой и `ai_function_throw_on_error` отключён. [`String`](/docs/ru/reference/data-types/string) **Примеры** **Перевод на французский** ```sql title=Query theme={null} SELECT aiTranslate('Hello, world!', 'French') ``` ```response title=Response theme={null} Bonjour le monde! ``` **Перевести на японский с учетом инструкций по стилю** ```sql title=Query theme={null} SELECT aiTranslate(body, 'Japanese', map('instructions', 'Use polite form (desu/masu)')) FROM articles LIMIT 5 ```