Функции ИИ

Документация по функциям ИИ

Функции ИИ — это встроенные функции 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

4

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

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