Перейти к основному содержимому
Перейти к основному содержимому

Функции ИИ

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

Примечание

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

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

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

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

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

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

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

ПараметрТипПо умолчаниюОписание
providerString—Провайдер модели. Поддерживаются: 'openai', 'anthropic'. См. примечание ниже.
endpointString—URL конечной точки API.
modelString—Имя модели (например, 'gpt-4o-mini', 'text-embedding-3-small').
api_keyString—Ключ аутентификации провайдера. Необязательно: если параметр не указан, заголовок аутентификации не отправляется, что позволяет обращаться к OpenAI-совместимым серверам, не требующим аутентификации.
max_tokensUInt641024Максимальное количество выходных токенов за один вызов API.
api_versionString—Строка версии API. Используется в Anthropic ('2023-06-01').
Примечание

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

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

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

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

URL endpoint в именованной коллекции AI — это URL конечной точки исходящего подключения, к которому сервер обращается от своего имени, потенциально передавая (если указано) 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.

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

Активность AI-функций отслеживается с помощью ClickHouse ProfileEvents:

ProfileEventDescription
AIAPICallsКоличество HTTP-запросов, отправленных AI-провайдеру.
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": "..."}, метка извлекается, и функция возвращает строку этой метки.

Первый аргумент — это именованная коллекция, которая задает provider, model, конечную точку и, при необходимости, API-ключ.

Синтаксис

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

Псевдонимы: AIClassify

Аргументы

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

Возвращаемое значение

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

Примеры

Классификация тональности

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

positive

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

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

aiEmbed​

Добавленный в: v26.6.0

Генерирует вектор эмбеддинга для заданного текста с помощью настроенного AI-провайдера.

Функция отправляет текст на настроенную конечную точку эмбеддингов и возвращает полученный вектор как Array(Float32). В пределах одного блока строк входные данные группируются в батчи размером до ai_function_embedding_max_batch_size элементов на один HTTP-запрос, чтобы уменьшить накладные расходы на каждый вызов.

Первый аргумент — именованная коллекция, которая задаёт провайдера, модель, конечную точку и, при необходимости, API-ключ. Необязательный аргумент dimensions, если он поддерживается моделью (например, text-embedding-3-* у OpenAI), запрашивает вектор заданного размера; в противном случае возвращается вектор стандартного для модели размера.

Синтаксис

aiEmbed(collection, text[, dimensions])

Аргументы

  • collection — Имя именованной коллекции, содержащей учетные данные провайдера и конфигурацию. String
  • text — Текст для получения эмбеддинга. String
  • dimensions — Необязательная целевая размерность выходного вектора. 0 или отсутствие значения означает исходную размерность модели. UInt64

Возвращаемое значение

Вектор эмбеддинга или пустой массив, если входное значение равно NULL или пусто, запрос завершился ошибкой и ai_function_throw_on_error отключён, либо квота была превышена при отключённом ai_function_throw_on_quota_exceeded. Array(Float32)

Примеры

Векторизация одной строки

SELECT aiEmbed('ai_credentials', 'Hello world')

С явно заданными измерениями

SELECT aiEmbed('ai_credentials', 'Hello world', 256)

Создание эмбеддингов для столбца с текстами

SELECT aiEmbed('ai_credentials', title, 256) FROM articles LIMIT 10

aiExtract​

Добавлено в: v26.4.0

Извлекает структурированную информацию из неструктурированного текста с помощью провайдера LLM.

Третий аргумент может быть либо произвольной инструкцией на естественном языке (например, 'the main complaint'), либо schema в формате JSON вида '{"field_a": "description of field a", "field_b": "description of field b"}'.

В режиме инструкции функция возвращает извлечённое значение в виде обычной строки или пустую строку, если ничего не найдено. В режиме schema функция возвращает строку JSON-объекта, ключи которого соответствуют запрошенной schema; отсутствующие поля имеют значение 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-объекта (в режиме schema). Возвращает значение по умолчанию для типа столбца (пустую строку), если запрос завершился ошибкой и ai_function_throw_on_error отключён. String

Примеры

Инструкция в свободной форме

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

late and damaged package

Извлечение schema

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

aiGenerate​

Добавлено в: v26.4.0

Генерирует произвольный текст по промпту с использованием провайдера LLM.

Функция отправляет промпт настроенному AI-провайдеру и возвращает сгенерированный текст. При необходимости можно указать системный промпт, чтобы направлять поведение модели (например, задать тон, формат или роль). Если системный промпт не указан, используется системный промпт по умолчанию: 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

Примеры

Простой вопрос

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

4

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

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

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

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

aiTranslate​

Добавлено в: v26.4.0

Переводит указанный текст на заданный язык с помощью провайдера LLM.

Дополнительные указания по стилю или диалекту можно передать в качестве четвертого аргумента (например, 'оставлять технические термины без перевода').

Первый аргумент — именованная коллекция, в которой указаны провайдер, модель, конечная точка и, при необходимости, 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

Примеры

Перевод на французский

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

Bonjour le monde!

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

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