Функции ИИ являются экспериментальными. Чтобы включить их, установите
allow_experimental_ai_functions.Функции ИИ могут возвращать непредсказуемые результаты. Результат во многом зависит от качества промпта и используемой модели.- Контроль квот: лимиты на количество токенов в рамках одного запроса (
ai_function_max_input_tokens_per_query,ai_function_max_output_tokens_per_query) и вызовов API (ai_function_max_api_calls_per_query). - Повторные попытки с задержкой: при временных сбоях выполняются повторные попытки (
ai_function_max_retries) с экспоненциально растущей задержкой (ai_function_retry_initial_delay_ms).
Конфигурация
aiGenerate, aiClassify, aiFilter, aiExtract, aiTranslate, aiRedact) и функций эмбеддингов (aiEmbed, aiSimilarity) можно определить отдельные именованные коллекции, так как им требуются разные конечные точки и обычно разные модели.
Пример оператора для создания именованной коллекции с учётными данными провайдера: одна — с конечной точкой для чата, другая — с конечной точкой для эмбеддингов:
Параметры именованной коллекции
Любой API, совместимый с OpenAI (например, vLLM, Ollama, LiteLLM), можно использовать, если задать
provider = 'openai' и указать в endpoint конечную точку вашего сервиса.Выбор учетных данных
- ключ
credentialsиз её карты параметров, если он указан; - в противном случае — соответствующую настройку учетных данных по умолчанию:
ai_function_text_default_credentialsдля текстовых функций (aiGenerate,aiClassify,aiFilter,aiExtract,aiTranslate,aiRedact);ai_function_embedding_default_credentialsдля функций эмбеддингов (aiEmbed,aiSimilarity).
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_.
Ограничение хостов конечных точек
endpoint в именованной коллекции AI — это исходящий пункт назначения, к которому сервер подключается от своего имени, потенциально передавая (если указан) api_key этой именованной коллекции в заголовках запроса. По умолчанию ClickHouse разрешает любой хост. Чтобы ограничить функции определённым набором провайдеров, настройте remote_url_allow_hosts в конфигурации сервера, например:
Безопасность передачи данных (HTTP vs HTTPS)
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 защищает данные только на сетевом участке между сервером и провайдером.
Поддерживаемые провайдеры
Обсервабилити
Запросите эти события:
aiClassify
credentials в необязательной карте параметров или из настройки
ai_function_text_default_credentials, если в карте этот ключ отсутствует.
Синтаксис
AIClassify
Аргументы
text— Текст для классификации.Stringcategories— Константный список возможных меток категорий.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
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— Текст для получения эмбеддинга.Stringmodel— Имя модели эмбеддингов.const Stringparams— Необязательная константаMap(String, String)с параметрами. Специфичный для функции ключ:dimensions(целевая размерность выходного вектора;0или отсутствие значения означает исходную размерность модели). Также применяется общий параметрcredentials(см. Функции ИИ).Map(String, String)
ai_function_throw_on_error отключён, либо была превышена квота при отключённом ai_function_throw_on_quota_exceeded. Array(Float32)
Примеры
Эмбеддинг одной строки (credentials можно опустить, если задана настройка ai_function_embedding_default_credentials)
Query
Query
Query
aiExtract
'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— Текст, из которого нужно извлечь информацию.Stringinstruction_or_schema— Инструкция для извлечения в свободной форме или константный объект JSON, описывающий извлекаемые поля.const Stringparams— Необязательный константныйMap(String, String)параметров. Ключи, специфичные для функции:temperature(температура сэмплирования, определяющая степень случайности; по умолчанию0.0),max_tokens(максимальное количество выходных токенов на вызов; по умолчанию1024). Также применяются общие параметрыcredentialsиmodel(см. функции ИИ).Map(String, String)
ai_function_throw_on_error отключён. String
Примеры
Инструкция в свободной форме
Query
Response
Query
aiFilter
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— Текст для оценки.Stringcondition— Постоянное условие на естественном языке, которому должен удовлетворять текст.Stringparams— Необязательный постоянный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
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— Пользовательский промпт или вопрос, отправляемый модели.Stringparams— Необязательный константный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
[REDACTED], настраивается через
параметр replacement). Массив categories ограничивает типы маскируемых PII; пустой массив
использует набор распространённых категорий по умолчанию (имя, email, номер телефона, адрес, кредитная карта, IP-адрес).
aiRedact предписывает модели изменять только обнаруженные диапазоны PII, однако сохранение окружающего текста
также выполняется в меру возможностей, поэтому модель всё равно может его изменить (см. предупреждение выше). Управляющие символы, кроме табуляции,
перевода строки и возврата каретки, перед отправкой запроса также заменяются пробелами, поэтому вывод
не является побайтно идентичным входным данным, содержащим такие символы.
Поскольку aiRedact возвращает весь входной текст с заменёнными PII, вывод имеет примерно ту же длину, что и входные данные.
Установите max_tokens (по умолчанию 1024) выше длины входных данных в токенах; ответ, усечённый из-за слишком низкого ограничения,
будет неполным.
Синтаксис
AIRedact
Аргументы
text— Текст для маскирования.Stringcategories— Постоянный список категорий 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)
ai_function_throw_on_error отключён. String
Примеры
Маскирование определённых категорий
Query
Response
Query
aiSimilarity
-1 присваивается
противоположным векторам эмбеддингов; семантически это означает, что тексты с оценками, близкими к -1, противоположны
по смыслу. Оценка 0 означает, что векторы ортогональны, то есть семантически не связаны. Наконец, оценка 1
означает, что векторы эмбеддингов направлены в одну сторону, а тексты с оценками, близкими к 1,
схожи по смыслу. Это дополнение cosineDistance для тех же эмбеддингов
(aiSimilarity = 1 - cosineDistance(embedding1, embedding2)).
Батчинг, учетные данные и параметр dimensions соответствуют aiEmbed, включая настройку
учетных данных по умолчанию ai_function_embedding_default_credentials.
Как и в aiEmbed, model — обязательный позиционный аргумент (константный String), который не считывается из
именованной коллекции или карты параметров.
Синтаксис
AISimilarity
Аргументы
text1— Первый текст.Stringtext2— Второй текст.Stringmodel— Имя модели эмбеддингов.const Stringparams— Необязательный константный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
Query
aiTranslate
instructions в карте параметров (например, 'keep technical terms untranslated').
Учетные данные (именованная коллекция, задающая провайдера, модель, конечную точку и, при необходимости, ключ API)
берутся из ключа credentials необязательной карты параметров или из
настройки ai_function_text_default_credentials, если в карте этот ключ отсутствует.
Синтаксис
AITranslate
Аргументы
text— Текст для перевода.Stringtarget_language— Название целевого языка или код BCP-47 (например,'French','es-MX').Stringparams— Необязательная константаMap(String, String)с параметрами. Ключи, специфичные для этой функции:temperature(температура сэмплирования, определяющая случайность; по умолчанию0.3),max_tokens(максимальное количество выходных токенов за один вызов; по умолчанию1024),instructions(дополнительные указания по стилю или диалекту для переводчика). Также применяются общие параметрыcredentialsиmodel(см. Функции ИИ).Map(String, String)
ai_function_throw_on_error отключён. String
Примеры
Перевод на французский
Query
Response
Query