Skip to main content
Функции ИИ — это встроенные функции ClickHouse, которые можно использовать для вызова ИИ или генерации эмбеддингов при работе с данными, извлечении информации, классификации данных и т. д.
Функции ИИ являются экспериментальными. Чтобы включить их, установите allow_experimental_ai_functions.
Функции ИИ могут возвращать непредсказуемые результаты. Результат во многом зависит от качества промпта и используемой модели.
Все функции используют общую инфраструктуру, которая обеспечивает:

Конфигурация

Функции ИИ используют именованную коллекцию, в которой хранятся учётные данные провайдера и параметры конфигурации. Для разных функций или их вызовов можно создавать и использовать разные именованные коллекции. Например, для текстовых функций (aiGenerate, aiClassify, aiExtract, aiTranslate) и функции aiEmbed можно определить отдельные именованные коллекции, так как им требуются разные конечные точки и обычно разные модели. Пример оператора для создания именованной коллекции с учётными данными провайдера: одна — с конечной точкой для чата, другая — с конечной точкой для эмбеддингов:

Параметры именованной коллекции

Любой API, совместимый с OpenAI (например, vLLM, Ollama, LiteLLM), можно использовать, если задать provider = 'openai' и указать в endpoint конечную точку вашего сервиса.

Выбор учетных данных

Функция определяет именованную коллекцию, которую следует использовать, в следующем порядке:
  1. ключ credentials из её карты параметров, если он указан;
  2. в противном случае — соответствующую настройку учетных данных по умолчанию:
Если не задано ни то ни другое, вызов завершится ошибкой. Для текстовых функций и функций эмбеддингов используются разные настройки по умолчанию, поскольку конечная точка для chat-completions отличается от конечной точки для эмбеддингов.

Карта параметров

Каждая функция принимает необязательный завершающий Map(String, String) с параметрами. Все значения — строки (числа заключайте в кавычки, например '0.2'). Неизвестные ключи отклоняются. Если ключ указан, он переопределяет соответствующее значение из именованной коллекции; если ключ отсутствует, используется значение из именованной коллекции (для model/max_tokens) или встроенное значение по умолчанию. Исключение — aiEmbed: в этой функции model передаётся как обязательный позиционный аргумент (aiEmbed(text, model[, params])), и если вместо этого задать его в карте параметров или именованной коллекции, возникнет ошибка. Следующие параметры являются общими для всех функций ИИ: Отдельные функции принимают дополнительные, специфичные для конкретной функции параметры (например, max_tokens, temperature, system_prompt, instructions и dimensions). Сведения о поддерживаемых параметрах и их значениях по умолчанию см. ниже в справочнике для каждой функции.

Настройки на уровне запроса

Все настройки, связанные с ИИ, перечислены в разделе Настройки и имеют префикс ai_function_.

Ограничение хостов конечных точек

URL endpoint в именованной коллекции AI — это исходящий пункт назначения, к которому сервер подключается от своего имени, потенциально передавая (если указан) api_key этой именованной коллекции в заголовках запроса. По умолчанию ClickHouse разрешает любой хост. Чтобы ограничить функции определённым набором провайдеров, настройте remote_url_allow_hosts в конфигурации сервера, например:
Обратите внимание, что этот параметр является общесерверным и применяется ко всем возможностям, использующим HTTP.

Безопасность передачи данных (HTTP vs HTTPS)

Способ передачи определяется исключительно схемой URL endpoint. Шифрования полезной нагрузки запроса на уровне приложения нет; защита данных при передаче полностью зависит от схемы:
  • https:// — соединение использует TLS. Тело запроса (входной текст, промпты) и api_key в заголовках запроса шифруются при передаче, а сертификат провайдера проверяется. Используйте этот вариант для любого удалённого провайдера.
  • http:// — соединение не шифруется. Тело запроса и api_key передаются в открытом виде. Используйте этот вариант только для доверенного провайдера в частной сети (например, для локального экземпляра vLLM или Ollama).
Функция ИИ не требует HTTPS принудительно: конечная точка http:// принимается, и данные отправляются без шифрования. Сейчас нет настройки на стороне сервера, которая отклоняла бы незашифрованные конечные точки ИИ — remote_url_allow_hosts ограничивает только хост пункта назначения и не проверяет схему URL, поэтому конечная точка http:// на разрешённом хосте всё равно проходит. Чтобы гарантировать шифрование при передаче, настройте именованные коллекции с конечными точками https://. Обратите внимание: в обоих случаях провайдер получает входные данные в открытом виде после завершения TLS; TLS защищает данные только на сетевом участке между сервером и провайдером.

Поддерживаемые провайдеры

Обсервабилити

Активность функции ИИ отслеживается через ClickHouse ProfileEvents: Запросите эти события:

aiClassify

Добавленный в: v26.4.0 Классифицирует заданный текст по одной из указанных категорий с помощью провайдера LLM. Функция отправляет текст вместе с фиксированным промптом для классификации и форматом ответа в виде JSON Schema, который ограничивает модель так, чтобы она возвращала ровно одну из переданных меток. Если ответ возвращается как объект JSON вида {"category": "..."}, метка извлекается, и функция возвращает строку этой метки. Учетные данные (именованная коллекция, задающая провайдера, модель, конечную точку и, при необходимости, ключ API) берутся из ключа credentials в необязательной карте параметров или из настройки ai_function_text_default_credentials, если в карте этот ключ отсутствует. Синтаксис
Псевдонимы: AIClassify Аргументы
  • text — Текст для классификации. String
  • categories — Константный список возможных меток категорий. Array(String)
  • params — Необязательный константный набор параметров Map(String, String). Ключи, специфичные для функции: temperature (температура сэмплирования, влияющая на случайность; по умолчанию 0.0), max_tokens (максимальное количество выходных токенов за один вызов; по умолчанию 1024). Также применяются общие параметры credentials и model (см. функции ИИ). Map(String, String)
Возвращаемое значение Одна из указанных меток категорий или значение по умолчанию для типа столбца (пустая строка), если при запросе произошла ошибка и ai_function_throw_on_error отключен. String Примеры Классификация тональности
Query
Response
Классификация столбца с явно заданными учетными данными
Query

aiEmbed

Добавленный в: v26.6.0 Генерирует эмбеддинг-вектор для заданного текста с использованием настроенного ИИ-провайдера. Функция отправляет текст в настроенную конечную точку эмбеддингов и возвращает полученный вектор как Array(Float32). В пределах одного блока строк входные данные группируются в батчи до 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-*), запрашивает вектор указанного размера; в противном случае возвращается собственная размерность модели. Синтаксис
Аргументы
  • text — Текст для получения эмбеддинга. String
  • model — Имя модели эмбеддингов. const String
  • params — Необязательная константа Map(String, String) с параметрами. Специфичный для функции ключ: dimensions (целевая размерность выходного вектора; 0 или отсутствие значения означает исходную размерность модели). Также применяется общий параметр credentials (см. Функции ИИ). Map(String, String)
Возвращаемое значение Эмбеддинг-вектор или пустой массив, если входное значение равно NULL или пусто, запрос завершился с ошибкой и ai_function_throw_on_error отключён, либо была превышена квота при отключённом ai_function_throw_on_quota_exceeded. Array(Float32) Примеры Эмбеддинг одной строки (credentials можно опустить, если задана настройка ai_function_embedding_default_credentials)
Query
С явно заданной размерностью
Query
Вычислить эмбеддинги для столбца с текстами
Query

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, если в карте этот ключ отсутствует. Синтаксис
Псевдонимы: AIExtract Аргументы
  • text — Текст, из которого нужно извлечь информацию. String
  • instruction_or_schema — Инструкция для извлечения в свободной форме или константный объект JSON, описывающий извлекаемые поля. const String
  • params — Необязательный константный Map(String, String) параметров. Ключи, специфичные для функции: temperature (температура сэмплирования, определяющая степень случайности; по умолчанию 0.0), max_tokens (максимальное количество выходных токенов на вызов; по умолчанию 1024). Также применяются общие параметры credentials и model (см. функции ИИ). Map(String, String)
Возвращаемое значение Одно извлечённое значение (режим инструкции) или строка с объектом JSON (режим схемы). Возвращает значение по умолчанию для типа столбца (пустую строку), если запрос завершился ошибкой и ai_function_throw_on_error отключён. String Примеры Инструкция в свободной форме
Query
Response
Извлечение схемы
Query

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. Синтаксис
Псевдонимы: AIGenerate Аргументы
  • prompt — Пользовательский промпт или вопрос, отправляемый модели. String
  • params — Необязательный константный Map(String, String) с параметрами. Специфичные для функции ключи: temperature (температура сэмплирования, управляющая случайностью; по умолчанию 0.7), max_tokens (максимальное число выходных токенов за один вызов; по умолчанию 1024), system_prompt (константная системная инструкция, определяющая поведение модели; по умолчанию — общий промпт ассистента). Также применяются общие параметры credentials и model (см. функции ИИ). Map(String, String)
Возвращаемое значение Сгенерированный текстовый ответ или значение по умолчанию для типа столбца (пустая строка), если запрос завершился ошибкой и ai_function_throw_on_error отключён. String Примеры Простой вопрос
Query
Response
С явными учетными данными и системным промптом
Query
Сводка значений столбца
Query

aiTranslate

Добавленный в: v26.4.0 Переводит заданный текст на указанный целевой язык с помощью провайдера LLM. Дополнительные указания по стилю или диалекту можно передать через ключ instructions в карте параметров (например, 'keep technical terms untranslated'). Учетные данные (именованная коллекция, задающая провайдера, модель, конечную точку и, при необходимости, ключ API) берутся из ключа credentials необязательной карты параметров или из настройки ai_function_text_default_credentials, если в карте этот ключ отсутствует. Синтаксис
Псевдонимы: AITranslate Аргументы
  • text — Текст для перевода. String
  • target_language — Название целевого языка или код BCP-47 (например, 'French', 'es-MX'). String
  • params — Необязательная константа Map(String, String) с параметрами. Ключи, специфичные для этой функции: temperature (температура сэмплирования, определяющая случайность; по умолчанию 0.3), max_tokens (максимальное количество выходных токенов за один вызов; по умолчанию 1024), instructions (дополнительные указания по стилю или диалекту для переводчика). Также применяются общие параметры credentials и model (см. Функции ИИ). Map(String, String)
Возвращаемое значение Переведённый текст или значение по умолчанию для типа столбца (пустая строка), если запрос завершился ошибкой и ai_function_throw_on_error отключён. String Примеры Перевод на французский
Query
Response
Перевести на японский с учетом инструкций по стилю
Query
Последнее изменение 23 июля 2026 г.