Функции ИИ являются экспериментальными. Чтобы включить их, установите
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, aiExtract, aiTranslate) и функции aiEmbed можно определить отдельные именованные коллекции, так как им требуются разные конечные точки и обычно разные модели.
Пример оператора для создания именованной коллекции с учётными данными провайдера: одна — с конечной точкой для чата, другая — с конечной точкой для эмбеддингов:
Параметры именованной коллекции
Любой API, совместимый с OpenAI (например, vLLM, Ollama, LiteLLM), можно использовать, если задать
provider = 'openai' и указать в endpoint конечную точку вашего сервиса.Выбор учетных данных
- ключ
credentialsиз её карты параметров, если он указан; - в противном случае — соответствующую настройку учетных данных по умолчанию:
ai_function_text_default_credentialsдля текстовых функций (aiGenerate,aiClassify,aiExtract,aiTranslate);ai_function_embedding_default_credentialsдляaiEmbed.
Карта параметров
Map(String, String) с параметрами. Все значения — строки (числа заключайте в кавычки, например '0.2'). Неизвестные ключи отклоняются. Если ключ указан, он переопределяет соответствующее значение из именованной коллекции; если ключ отсутствует, используется значение из именованной коллекции (для model/max_tokens) или встроенное значение по умолчанию. Исключение — aiEmbed: в этой функции model передаётся как обязательный позиционный аргумент (aiEmbed(text, 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).
http:// принимается, и данные отправляются без шифрования. Сейчас нет настройки на стороне сервера, которая отклоняла бы незашифрованные конечные точки ИИ — remote_url_allow_hosts ограничивает только хост пункта назначения и не проверяет схему URL, поэтому конечная точка http:// на разрешённом хосте всё равно проходит. Чтобы гарантировать шифрование при передаче, настройте именованные коллекции с конечными точками https://.
Обратите внимание: в обоих случаях провайдер получает входные данные в открытом виде после завершения TLS; TLS защищает данные только на сетевом участке между сервером и провайдером.
Поддерживаемые провайдеры
Обсервабилити
Запросите эти события:
aiClassify
{"category": "..."}, метка извлекается, и функция возвращает строку этой метки.
Учетные данные (именованная коллекция, задающая провайдера, модель, конечную точку и, при необходимости, ключ API)
берутся из ключа 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-*),
запрашивает вектор указанного размера; в противном случае возвращается собственная размерность модели.
Синтаксис
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
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
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