Функции ИИ - ClickHouse Documentation

Функции ИИ — это встроенные функции ClickHouse, которые можно использовать для вызова ИИ или генерации эмбеддингов при работе с данными, извлечении информации, классификации данных и т. д.

Функции ИИ могут возвращать непредсказуемые результаты. Результат во многом зависит от качества промпта и используемой модели.

Все функции используют общую инфраструктуру, которая обеспечивает:

Контроль квот: лимиты на количество токенов в рамках одного запроса (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).

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

Функции ИИ ссылаются на именованную коллекцию, в которой хранятся учетные данные провайдера и параметры конфигурации. Первый аргумент каждой функции — имя этой коллекции. Пример оператора для создания именованной коллекции с учетными данными провайдера:

CREATE NAMED COLLECTION ai_credentials AS
    provider = 'openai',
    endpoint = 'https://api.openai.com/v1/chat/completions',
    model = 'gpt-4o-mini',
    api_key = 'sk-...';

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

Параметр	Тип	По умолчанию	Описание
`provider`	String	—	Провайдер модели. Поддерживаются: `'openai'`, `'anthropic'`. См. примечание ниже.
`endpoint`	String	—	URL конечной точки API.
`model`	String	—	Имя модели (например, `'gpt-4o-mini'`, `'text-embedding-3-small'`).
`api_key`	String	—	Ключ аутентификации для провайдера.
`max_tokens`	UInt64	`1024`	Максимальное количество выходных токенов на один вызов API.
`api_version`	String	—	Строка версии API. Используется в Anthropic (`'2023-06-01'`).

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

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

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

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

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

<remote_url_allow_hosts>
    <host>api.openai.com</host>
    <host>api.anthropic.com</host>
</remote_url_allow_hosts>

Обратите внимание, что этот параметр является общесерверным и применяется ко всем возможностям, использующим HTTP.

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

Провайдер	Значение `provider`	Функции чата	Примечания
OpenAI	`'openai'`	Да	Провайдер по умолчанию.
Anthropic	`'anthropic'`	Да	Использует конечную точку `/v1/messages`.

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

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

ProfileEvent	Description
`AIAPICalls`	Количество HTTP-запросов, отправленных провайдеру ИИ.
`AIInputTokens`	Общее количество использованных входных токенов.
`AIOutputTokens`	Общее количество использованных выходных токенов.
`AIRowsProcessed`	Количество строк, для которых был получен результат.
`AIRowsSkipped`	Количество пропущенных строк (превышена квота или возникла ошибка при `ai_function_throw_on_error = 0`).

Запросите эти события:

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;

aiClassify

Добавленный в: v26.4.0 Классифицирует заданный текст по одной из указанных категорий с помощью провайдера LLM. Функция отправляет текст вместе с фиксированным промптом для классификации и форматом ответа в виде JSON Schema, который ограничивает модель так, чтобы она возвращала ровно одну из переданных меток. Если ответ возвращается как JSON-объект вида {"category": "..."}, метка извлекается, и функция возвращает строку этой метки. Первый аргумент — именованная коллекция, в которой указываются провайдер, модель, конечная точка и ключ API. Синтаксис

aiClassify(collection, text, categories[, temperature])

Псевдонимы: AIClassify Аргументы

collection — Имя именованной коллекции, содержащей учетные данные провайдера и конфигурацию. String
text — Текст для классификации. String
categories — Константный список возможных меток категорий. Array(String)
temperature — Температура сэмплирования, влияющая на случайность. По умолчанию: 0.0. Float64

Возвращаемое значение Одна из указанных меток категорий или значение по умолчанию для типа столбца (пустая строка), если при запросе произошла ошибка и ai_function_throw_on_error отключен. String Примеры Классификация тональности

Query

SELECT aiClassify('ai_credentials', 'I love this product!', ['positive', 'negative', 'neutral'])

Response

positive

Классификация столбца

Query

SELECT body, aiClassify('ai_credentials', body, ['bug', 'question', 'feature']) AS kind FROM issues LIMIT 5

Response

aiExtract

Добавленный в: v26.4.0 Извлекает структурированную информацию из неструктурированного текста с помощью провайдера LLM. Третий аргумент может быть либо произвольной инструкцией на естественном языке (например, 'the main complaint'), либо JSON-кодированной схемой вида '{"field_a": "description of field a", "field_b": "description of field b"}'. В режиме инструкции функция возвращает извлечённое значение в виде обычной строки или пустую строку, если ничего не найдено. В режиме схемы функция возвращает строку с объектом JSON, ключи которого соответствуют запрошенной схеме; отсутствующие поля имеют значение null. Первый аргумент — именованная коллекция, в которой задаются провайдер, модель, конечная точка и API-ключ. Синтаксис

aiExtract(collection, text, instruction_or_schema[, temperature])

Псевдонимы: AIExtract Аргументы

collection — Имя именованной коллекции, содержащей учетные данные провайдера и конфигурацию. String
text — Текст, из которого нужно извлечь информацию. String
instruction_or_schema — Инструкция для извлечения в свободной форме или константный объект JSON, описывающий извлекаемые поля. const String
temperature — Температура сэмплирования, определяющая степень случайности. По умолчанию: 0.0. const Float64

Возвращаемое значение Одно извлечённое значение (режим инструкции) или строка с объектом JSON (режим схемы). Возвращает значение по умолчанию для типа столбца (пустую строку), если запрос завершился ошибкой и ai_function_throw_on_error отключён. String Примеры Инструкция в свободной форме

Query

SELECT aiExtract('ai_credentials', 'The package arrived late and was damaged.', 'the main complaint')

Response

late and damaged package

Извлечение схемы

Query

SELECT aiExtract('ai_credentials', review, '{"sentiment": "positive, negative or neutral", "topic": "main topic of the review"}') FROM reviews LIMIT 5

Response

aiGenerate

Добавленный в: v26.4.0 Генерирует текст произвольной формы из промпта с помощью провайдера LLM. Функция отправляет промпт настроенному провайдеру ИИ и возвращает сгенерированный текст. Чтобы задать поведение модели (например, тон, формат или роль), можно передать необязательный системный промпт. Если системный промпт не указан, по умолчанию используется: You are a helpful assistant. Provide a clear and concise response. Первый аргумент — именованная коллекция, в которой задаются провайдер, модель, конечная точка и ключ API. Синтаксис

aiGenerate(collection, prompt[, system_prompt[, temperature]])

Псевдонимы: AIGenerate Аргументы

collection — Имя именованной коллекции, содержащей учётные данные провайдера и конфигурацию. String
prompt — Промпт или вопрос пользователя, отправляемый модели. String
system_prompt — Необязательная постоянная системная инструкция, определяющая поведение модели (например, роль или формат вывода), которая отправляется вместе с каждым промптом. String
temperature — Температура сэмплирования, управляющая случайностью. Значение по умолчанию: 0.7. Float64

Возвращаемое значение Сгенерированный текстовый ответ или значение по умолчанию для типа столбца (пустая строка), если запрос завершился ошибкой и ai_function_throw_on_error отключён. String Примеры Простой вопрос

Query

SELECT aiGenerate('ai_credentials', 'What is 2 + 2? Reply with just the number.')

Response

С системным промптом

Query

SELECT aiGenerate('ai_credentials', 'Explain ClickHouse', 'You are a database expert. Be concise.')

Response

Сводка значений столбца

Query

SELECT article_title, aiGenerate('ai_credentials', concat('Summarize in one sentence: ', article_body)) AS summary FROM articles LIMIT 5

Response

aiTranslate

Добавленный в: v26.4.0 Переводит заданный текст на указанный целевой язык с помощью провайдера LLM. Дополнительные указания по стилю или диалекту можно передать в качестве четвертого аргумента (например, 'keep technical terms untranslated'). Первый аргумент — именованная коллекция, в которой указаны провайдер, модель, конечная точка и ключ API. Синтаксис

aiTranslate(collection, text, target_language[, instructions[, temperature]])

Псевдонимы: AITranslate Аргументы

collection — Имя именованной коллекции, содержащей учетные данные провайдера и конфигурацию. String
text — Текст для перевода. String
target_language — Имя целевого языка или код BCP-47 (например, 'French', 'es-MX'). String
instructions — Необязательные дополнительные инструкции для переводчика в виде константы. String
temperature — Температура сэмплирования, управляющая случайностью. По умолчанию: 0.3. Float64

Возвращаемое значение Переведённый текст или значение по умолчанию для типа столбца (пустая строка), если запрос завершился ошибкой и ai_function_throw_on_error отключён. String Примеры Перевод на французский

Query

SELECT aiTranslate('ai_credentials', 'Hello, world!', 'French')

Response

Bonjour le monde!

Переведите на японский с учетом указаний по стилю

Query

SELECT aiTranslate('ai_credentials', body, 'Japanese', 'Use polite form (desu/masu)') FROM articles LIMIT 5

Response

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

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

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

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

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

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

​aiClassify

​aiExtract

​aiGenerate

​aiTranslate

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

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

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

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

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

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

aiClassify

aiExtract

aiGenerate

aiTranslate