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

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

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

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

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

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

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

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

Каждая функция принимает необязательный завершающий Map(String, String) с параметрами. Все значения — строки (числа заключайте в кавычки, например '0.2'). Неизвестные ключи отклоняются. Если ключ указан, он переопределяет соответствующее значение из именованной коллекции; если ключ отсутствует, используется значение из именованной коллекции (для model/max_tokens) или встроенное значение по умолчанию. Исключение — функции эмбеддингов (aiEmbed, aiSimilarity): в них model передаётся как обязательный позиционный аргумент (например, aiEmbed(text, model[, params]), aiSimilarity(text1, text2, 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).
По умолчанию функции ИИ отклоняют endpoint, который отправлял бы данные в открытом виде на удалённый хост: любая конечная точка, отличная от HTTPS, хост которой не является loopback-адресом, вызывает исключение. Loopback-хосты (localhost, 127.0.0.0/8, ::1) являются исключением, поэтому локальный сервер моделей http://localhost работает без дополнительной настройки. Чтобы разрешить незашифрованную конечную точку http:// на удалённом хосте, установите ai_function_allow_insecure_endpoint в значение 1. Эта проверка не зависит от remote_url_allow_hosts: эта настройка представляет собой список разрешённых хостов и не проверяет схему URL, поэтому конечная точка http://, указывающая на разрешённый хост, всё равно проходит её. Обратите внимание: в обоих случаях провайдер получает входные данные в открытом виде после завершения TLS; TLS защищает данные только на сетевом участке между сервером и провайдером.

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

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

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

aiClassify

Добавленный в: v26.4.0 Классифицирует заданный текст по одной из указанных категорий с помощью провайдера LLM. Учетные данные (именованная коллекция, задающая провайдера, модель, конечную точку и, при необходимости, ключ 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 Генерирует эмбеддинг-вектор для заданного текста с использованием настроенного AI-провайдера. Функция отправляет текст в настроенную конечную точку эмбеддингов и возвращает полученный вектор как 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-*), запрашивает вектор указанного размера; в противном случае возвращается собственная размерность модели. Синтаксис
Псевдонимы: AIEmbed Аргументы
  • 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

aiFilter

Добавлено в: v26.8.0 Проверяет условие, заданное на естественном языке, по указанному тексту с помощью провайдера LLM и возвращает булево значение (UInt8), пригодное для использования в WHERE, PREWHERE и JOIN ... ON. Функция запрашивает у модели ответ только в виде true или false в нижнем регистре. Неудачные запросы (когда ai_function_throw_on_error отключён) и нераспознанные ответы преобразуются в 0, поэтому строка отфильтровывается. Предупреждение: Не доверяйте результатам aiFilter без тщательной проверки. Предикаты на основе LLM могут быть некорректными или непоследовательными; используйте их только там, где допустимы ложноположительные и ложноотрицательные срабатывания. Учётные данные (именованная коллекция, содержащая провайдера, модель, конечную точку и, при необходимости, ключ API) берутся из ключа credentials необязательной карты параметров или из настройки ai_function_text_default_credentials, если карта не содержит этого ключа. Примечание: при использовании aiFilter в JOIN ... ON LLM вызывается один раз для каждой пары кандидатов, что может быть затратно. Синтаксис
Псевдонимы: AIFilter Аргументы
  • text — Текст для оценки. String
  • condition — Постоянное условие на естественном языке, которому должен удовлетворять текст. String
  • params — Необязательный постоянный Map(String, String) параметров. Специфичные для функции ключи: temperature (температура сэмплирования, определяющая случайность; по умолчанию 0.0), max_tokens (максимальное количество выходных токенов за вызов; по умолчанию 1024). Также применяются общие параметры credentials и model (см. функции ИИ). Map(String, String)
Возвращаемое значение 1, если текст соответствует условию, иначе 0. Возвращает значение по умолчанию (0), если запрос завершился ошибкой и ai_function_throw_on_error отключён. UInt8 Примеры Фильтрация гневных отзывов
Query
Фильтрация столбца с явно заданными учётными данными
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

aiRedact

Добавлено в: v26.8.0 Обнаруживает и маскирует персональные данные (PII) в заданном тексте с помощью провайдера LLM.
aiRedact обнаруживает и маскирует PII с помощью LLM в меру своих возможностей, поэтому его вывод ненадёжен. Обнаружение и удаление PII зависят от выбранной модели, промпта и входных данных: модель может пропустить идентификаторы, замаскировать их лишь частично или изменить окружающий текст. Функция лучше всего работает с грамотно составленным английским текстом; для других языков или текста с большим количеством орфографических, пунктуационных или грамматических ошибок результаты могут быть хуже. aiRedact не гарантирует отсутствие PII в своём выводе и не должен рассматриваться как самостоятельный безопасный или достаточный механизм анонимизации. Перед передачей данных недоверенным сторонам всегда проверяйте вывод, чтобы убедиться, что он соответствует политикам вашей организации в области конфиденциальности данных и соблюдения нормативных требований.
Каждый обнаруженный диапазон PII заменяется токеном маскирования (по умолчанию [REDACTED], настраивается через параметр replacement). Массив categories ограничивает типы маскируемых PII; пустой массив использует набор распространённых категорий по умолчанию (имя, email, номер телефона, адрес, кредитная карта, IP-адрес). aiRedact предписывает модели изменять только обнаруженные диапазоны PII, однако сохранение окружающего текста также выполняется в меру возможностей, поэтому модель всё равно может его изменить (см. предупреждение выше). Управляющие символы, кроме табуляции, перевода строки и возврата каретки, перед отправкой запроса также заменяются пробелами, поэтому вывод не является побайтно идентичным входным данным, содержащим такие символы. Поскольку aiRedact возвращает весь входной текст с заменёнными PII, вывод имеет примерно ту же длину, что и входные данные. Установите max_tokens (по умолчанию 1024) выше длины входных данных в токенах; ответ, усечённый из-за слишком низкого ограничения, будет неполным. Синтаксис
Псевдонимы: AIRedact Аргументы
  • text — Текст для маскирования. String
  • categories — Постоянный список категорий PII, подлежащих маскированию (например, ['name', 'ssn', 'credit_card']). При пустом массиве используется набор распространённых категорий по умолчанию (имя, электронная почта, номер телефона, адрес, кредитная карта, IP-адрес). Array(String)
  • params — Необязательный постоянный Map(String, String) параметров. Специфичные для функции ключи: temperature (температура сэмплирования, управляющая случайностью; по умолчанию 0.0), max_tokens (максимальное количество выходных токенов за вызов; по умолчанию 1024 — поскольку aiRedact возвращает полный текст, задайте значение больше длины входного текста в токенах, иначе ответ может быть усечённым и неполным), replacement (токен, заменяющий каждый обнаруженный фрагмент PII; по умолчанию [REDACTED]). Также применяются общие параметры credentials и model (см. Функции ИИ). Map(String, String)
Возвращаемое значение Текст, в котором обнаруженные PII заменены токеном маскирования, или значение по умолчанию для типа столбца (пустая строка), если запрос завершился с ошибкой и ai_function_throw_on_error отключён. String Примеры Маскирование определённых категорий
Query
Response
Маскировка категорий PII по умолчанию с помощью пользовательского токена
Query

aiSimilarity

Добавлено в: v26.8.0 Вычисляет семантическое сходство двух текстов с помощью настроенного провайдера эмбеддингов. Вычисляет векторные эмбеддинги обоих текстов и возвращает их косинусное сходство. Оценка -1 присваивается противоположным векторам эмбеддингов; семантически это означает, что тексты с оценками, близкими к -1, противоположны по смыслу. Оценка 0 означает, что векторы ортогональны, то есть семантически не связаны. Наконец, оценка 1 означает, что векторы эмбеддингов направлены в одну сторону, а тексты с оценками, близкими к 1, схожи по смыслу. Это дополнение cosineDistance для тех же эмбеддингов (aiSimilarity = 1 - cosineDistance(embedding1, embedding2)). Батчинг, учетные данные и параметр dimensions соответствуют aiEmbed, включая настройку учетных данных по умолчанию ai_function_embedding_default_credentials. Как и в aiEmbed, model — обязательный позиционный аргумент (константный String), который не считывается из именованной коллекции или карты параметров. Синтаксис
Псевдонимы: AISimilarity Аргументы
  • text1 — Первый текст. String
  • text2 — Второй текст. String
  • model — Имя модели эмбеддингов. const String
  • params — Необязательный константный Map(String, String) параметров. Ключ, специфичный для этой функции: dimensions (целевая размерность эмбеддингов; 0 или отсутствие значения означает собственную размерность модели). Также применяется общий параметр credentials (см. функции ИИ). Map(String, String)
Возвращаемое значение Косинусное сходство в диапазоне [-1, 1] или NULL, если один из текстов имеет значение NULL или пуст, запрос на создание эмбеддинга завершился ошибкой при отключённом ai_function_throw_on_error либо квота была превышена при отключённом ai_function_throw_on_quota_exceeded. Nullable(Float32) Примеры Сравнение двух строк (credentials можно не указывать, если задана настройка ai_function_embedding_default_credentials)
Query
Ранжируйте отзывы по схожести с запросом
Query
Семантическая дедупликация с использованием self-join
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
Последнее изменение 14 августа 2026 г.