> ## Documentation Index > Fetch the complete documentation index at: https://clickhouse.com/docs/llms.txt > Use this file to discover all available pages before exploring further. > Документация по функциям ИИ # Функции ИИ Функции ИИ — это встроенные функции ClickHouse, которые можно использовать для вызова ИИ или генерации эмбеддингов при работе с данными, извлечении информации, классификации данных и т. д. Функции ИИ являются экспериментальными. Чтобы включить их, установите [`allow_experimental_ai_functions`](/docs/ru/reference/settings/session-settings/allow-experimental#allow_experimental_ai_functions). Функции ИИ могут возвращать непредсказуемые результаты. Результат во многом зависит от качества промпта и используемой модели. **Внедрение промпта** Входной текст отправляется модели и может влиять на её вывод (внедрение промпта). Текст из внешних, непроверенных или неочищенных источников может содержать инструкции, из-за которых модель вернёт содержимое, контролируемое злоумышленником, проигнорирует требуемый формат или создаст вредоносную полезную нагрузку. Считайте вывод функции ИИ недоверенным: проверяйте или очищайте его перед использованием на последующих этапах, таких как построение SQL, команд оболочки, дальнейших запросов или принятие решений по контролю доступа. Все функции используют общую инфраструктуру, которая обеспечивает: * **Контроль квот**: лимиты на количество токенов в рамках одного запроса ([`ai_function_max_input_tokens_per_query`](/docs/ru/reference/settings/session-settings/ai-function#ai_function_max_input_tokens_per_query), [`ai_function_max_output_tokens_per_query`](/docs/ru/reference/settings/session-settings/ai-function#ai_function_max_output_tokens_per_query)) и вызовов API ([`ai_function_max_api_calls_per_query`](/docs/ru/reference/settings/session-settings/ai-function#ai_function_max_api_calls_per_query)). * **Повторные попытки с задержкой**: при временных сбоях выполняются повторные попытки ([`ai_function_max_retries`](/docs/ru/reference/settings/session-settings/ai-function#ai_function_max_retries)) с экспоненциально растущей задержкой ([`ai_function_retry_initial_delay_ms`](/docs/ru/reference/settings/session-settings/ai-function#ai_function_retry_initial_delay_ms)).
## Конфигурация
Функции ИИ используют **именованную коллекцию**, в которой хранятся учётные данные провайдера и параметры конфигурации. Для разных функций или их вызовов можно создавать и использовать разные именованные коллекции. Например, для текстовых функций (`aiGenerate`, `aiClassify`, `aiFilter`, `aiExtract`, `aiTranslate`, `aiRedact`) и функций эмбеддингов (`aiEmbed`, `aiSimilarity`) можно определить отдельные именованные коллекции, так как им требуются разные конечные точки и обычно разные модели. Пример оператора для создания именованной коллекции с учётными данными провайдера: одна — с конечной точкой для чата, другая — с конечной точкой для эмбеддингов: ```sql theme={null} CREATE NAMED COLLECTION ai_text_credentials AS provider = 'openai', endpoint = 'https://api.openai.com/v1/chat/completions', model = 'gpt-4o-mini', api_key = 'sk-...'; -- The embedding functions (`aiEmbed`, `aiSimilarity`) do not read `model` from the named collection, -- pass it as a positional argument instead. Defining `model` in an embedding collection is an error, -- not silently ignored. CREATE NAMED COLLECTION ai_embedding_credentials AS provider = 'openai', endpoint = 'https://api.openai.com/v1/embeddings', api_key = 'sk-...'; ```
### Параметры именованной коллекции
| Параметр | Тип | По умолчанию | Описание | | ------------- | ------ | ------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `provider` | String | — | Провайдер модели. Поддерживаются: `'openai'`, `'anthropic'`. См. примечание ниже. | | `endpoint` | String | — | URL конечной точки API. | | `model` | String | — | Имя модели (например, `'gpt-4o-mini'`). Используется текстовыми функциями; функции эмбеддингов (`aiEmbed`, `aiSimilarity`) требуют `model` в качестве позиционного аргумента и возвращают ошибку, если `model` указан в именованной коллекции. | | `api_key` | String | — | Ключ аутентификации для провайдера. Необязательно: если параметр не указан, заголовок аутентификации не отправляется, что позволяет использовать OpenAI-совместимые серверы, не требующие аутентификации. | | `max_tokens` | UInt64 | `1024` | Максимальное количество выходных токенов на один вызов API. | | `api_version` | String | — | Строка версии API. Используется в Anthropic (`'2023-06-01'`). | Любой API, совместимый с OpenAI (например, vLLM, Ollama, LiteLLM), можно использовать, если задать `provider = 'openai'` и указать в `endpoint` конечную точку вашего сервиса.
### Выбор учетных данных
Функция определяет именованную коллекцию, которую следует использовать, в следующем порядке: 1. ключ `credentials` из её карты параметров, если он указан; 2. в противном случае — соответствующую настройку учетных данных по умолчанию: * [`ai_function_text_default_credentials`](/docs/ru/reference/settings/session-settings/ai-function#ai_function_text_default_credentials) для текстовых функций (`aiGenerate`, `aiClassify`, `aiFilter`, `aiExtract`, `aiTranslate`, `aiRedact`); * [`ai_function_embedding_default_credentials`](/docs/ru/reference/settings/session-settings/ai-function#ai_function_embedding_default_credentials) для функций эмбеддингов (`aiEmbed`, `aiSimilarity`). Если не задано ни то ни другое, вызов завершится ошибкой. Для текстовых функций и функций эмбеддингов используются разные настройки по умолчанию, поскольку конечная точка для chat-completions отличается от конечной точки для эмбеддингов. ```sql theme={null} SET ai_function_text_default_credentials = 'ai_text_credentials'; -- Uses ai_text_credentials from the setting: SELECT aiGenerate('What is 2 + 2? Reply with just the number.'); -- Overrides the default for this call: SELECT aiGenerate('Bonjour', map('credentials', 'other_credentials')); ``` Фильтруйте строки по условию на естественном языке с помощью `aiFilter`, которая возвращает `UInt8` и может использоваться непосредственно в предложении `WHERE`: ```sql theme={null} SELECT * FROM reviews WHERE aiFilter(body, 'the customer is angry about shipping'); ```
### Карта параметров
Каждая функция принимает необязательный завершающий `Map(String, String)` с параметрами. Все значения — строки (числа заключайте в кавычки, например `'0.2'`). Неизвестные ключи отклоняются. Если ключ указан, он переопределяет соответствующее значение из именованной коллекции; если ключ отсутствует, используется значение из именованной коллекции (для `model`/`max_tokens`) или встроенное значение по умолчанию. Исключение — функции эмбеддингов (`aiEmbed`, `aiSimilarity`): в них `model` передаётся как обязательный позиционный аргумент (например, `aiEmbed(text, model[, params])`, `aiSimilarity(text1, text2, model[, params])`), и если вместо этого задать его в карте параметров или именованной коллекции, возникнет ошибка. Это необходимо для обеспечения воспроизводимости эмбеддингов. Следующие параметры являются общими для всех функций ИИ: | Key | Description | | ------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `credentials` | Именованная коллекция для использования (см. выше). | | `model` | Переопределяет `model` коллекции (только для текстовых функций; в функциях эмбеддингов (`aiEmbed`, `aiSimilarity`) `model` передаётся как обязательный позиционный аргумент, а не как ключ карты). | Отдельные функции принимают дополнительные, специфичные для конкретной функции параметры (например, `max_tokens`, `temperature`, `system_prompt`, `instructions` и `dimensions`). Сведения о поддерживаемых параметрах и их значениях по умолчанию см. ниже в справочнике для каждой функции. ```sql theme={null} SELECT aiGenerate(body, map('temperature', '0.2', 'system_prompt', 'You are terse.')) FROM articles; ```
### Настройки на уровне запроса
Все настройки, связанные с ИИ, перечислены в разделе [Настройки](/docs/ru/reference/settings/session-settings) и имеют префикс `ai_function_`.
### Ограничение хостов конечных точек
URL `endpoint` в именованной коллекции AI — это исходящий пункт назначения, к которому сервер подключается от своего имени, потенциально передавая (если указан) `api_key` этой именованной коллекции в заголовках запроса. По умолчанию ClickHouse разрешает любой хост. Чтобы ограничить функции определённым набором провайдеров, настройте [`remote_url_allow_hosts`](/docs/ru/reference/settings/server-settings/settings/remote#remote_url_allow_hosts) в конфигурации сервера, например: ```xml theme={null} api.openai.com api.anthropic.com ``` Обратите внимание, что этот параметр является общесерверным и применяется ко всем возможностям, использующим HTTP.
### Безопасность передачи данных (HTTP vs HTTPS)
Способ передачи определяется исключительно схемой URL `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`](/docs/ru/reference/settings/session-settings/ai-function#ai_function_allow_insecure_endpoint) в значение `1`. Эта проверка не зависит от [`remote_url_allow_hosts`](/docs/ru/reference/settings/server-settings/settings/remote#remote_url_allow_hosts): эта настройка представляет собой список разрешённых хостов и не проверяет схему URL, поэтому конечная точка `http://`, указывающая на разрешённый хост, всё равно проходит её. Обратите внимание: в обоих случаях провайдер получает входные данные в открытом виде после завершения TLS; TLS защищает данные только на сетевом участке между сервером и провайдером.
## Поддерживаемые провайдеры
| Провайдер | Значение `provider` | Функции чата | Примечания | | --------- | ------------------- | ------------ | ----------------------------------------- | | OpenAI | `'openai'` | Да | Провайдер по умолчанию. | | Anthropic | `'anthropic'` | Да | Использует конечную точку `/v1/messages`. |
## Обсервабилити
Активность функции ИИ отслеживается через ClickHouse [ProfileEvents](/docs/ru/reference/system-tables/query_log): | ProfileEvent | Description | | ----------------- | -------------------------------------------------------------------------------------------------------- | | `AIAPICalls` | Количество HTTP-запросов, отправленных провайдеру ИИ. | | `AIInputTokens` | Общее количество использованных входных токенов. | | `AIOutputTokens` | Общее количество использованных выходных токенов. | | `AIRowsProcessed` | Количество строк, для которых был получен результат. | | `AIRowsSkipped` | Количество пропущенных строк (превышена квота или возникла ошибка при `ai_function_throw_on_error = 0`). | Запросите эти события: ```sql theme={null} 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. Учетные данные (именованная коллекция, задающая провайдера, модель, конечную точку и, при необходимости, ключ API) берутся из ключа `credentials` в необязательной карте параметров или из настройки `ai_function_text_default_credentials`, если в карте этот ключ отсутствует. **Синтаксис** ```sql theme={null} aiClassify(text, categories[, params]) ``` **Псевдонимы**: `AIClassify` **Аргументы** * `text` — Текст для классификации. [`String`](/docs/ru/reference/data-types/string) * `categories` — Константный список возможных меток категорий. [`Array(String)`](/docs/ru/reference/data-types/array) * `params` — Необязательный константный набор параметров `Map(String, String)`. Ключи, специфичные для функции: `temperature` (температура сэмплирования, влияющая на случайность; по умолчанию `0.0`), `max_tokens` (максимальное количество выходных токенов за один вызов; по умолчанию `1024`). Также применяются общие параметры `credentials` и `model` (см. [функции ИИ](/docs/ru/reference/functions/regular-functions/ai-functions)). [`Map(String, String)`](/docs/ru/reference/data-types/map) **Возвращаемое значение** Одна из указанных меток категорий или значение по умолчанию для типа столбца (пустая строка), если при запросе произошла ошибка и `ai_function_throw_on_error` отключен. [`String`](/docs/ru/reference/data-types/string) **Примеры** **Классификация тональности** ```sql title=Query theme={null} SELECT aiClassify('I love this product!', ['positive', 'negative', 'neutral']) ``` ```response title=Response theme={null} positive ``` **Классификация столбца с явно заданными учетными данными** ```sql title=Query theme={null} SELECT body, aiClassify(body, ['bug', 'question', 'feature'], map('credentials', 'ai_text_credentials')) AS kind FROM issues LIMIT 5 ```
## aiEmbed
Добавленный в: v26.6.0 Генерирует эмбеддинг-вектор для заданного текста с использованием настроенного AI-провайдера. Функция отправляет текст в настроенную конечную точку эмбеддингов и возвращает полученный вектор как `Array(Float32)`. В пределах одного блока строк входные данные группируются в батчи до [`ai_function_embedding_max_batch_size`](/docs/ru/reference/settings/session-settings/ai-function#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-*`), запрашивает вектор указанного размера; в противном случае возвращается собственная размерность модели. **Синтаксис** ```sql theme={null} aiEmbed(text, model[, params]) ``` **Псевдонимы**: `AIEmbed` **Аргументы** * `text` — Текст для получения эмбеддинга. [`String`](/docs/ru/reference/data-types/string) * `model` — Имя модели эмбеддингов. [`const String`](/docs/ru/reference/data-types/string) * `params` — Необязательная константа `Map(String, String)` с параметрами. Специфичный для функции ключ: `dimensions` (целевая размерность выходного вектора; `0` или отсутствие значения означает исходную размерность модели). Также применяется общий параметр `credentials` (см. [Функции ИИ](/docs/ru/reference/functions/regular-functions/ai-functions)). [`Map(String, String)`](/docs/ru/reference/data-types/map) **Возвращаемое значение** Эмбеддинг-вектор или пустой массив, если входное значение равно NULL или пусто, запрос завершился с ошибкой и `ai_function_throw_on_error` отключён, либо была превышена квота при отключённом `ai_function_throw_on_quota_exceeded`. [`Array(Float32)`](/docs/ru/reference/data-types/array) **Примеры** **Эмбеддинг одной строки (`credentials` можно опустить, если задана настройка `ai_function_embedding_default_credentials`)** ```sql title=Query theme={null} SELECT aiEmbed('Hello world', 'text-embedding-3-small', map('credentials', 'ai_embedding_credentials')) ``` **С явно заданной размерностью** ```sql title=Query theme={null} SELECT aiEmbed('Hello world', 'text-embedding-3-small', map('credentials', 'ai_embedding_credentials', 'dimensions', '256')) ``` **Вычислить эмбеддинги для столбца с текстами** ```sql title=Query theme={null} SELECT aiEmbed(title, 'text-embedding-3-small', map('credentials', 'ai_embedding_credentials', 'dimensions', '256')) FROM articles LIMIT 10 ```
## aiExtract
Добавленный в: v26.4.0 Извлекает структурированную информацию из неструктурированного текста с помощью провайдера LLM. Третий аргумент может быть либо произвольной инструкцией на естественном языке (например, `'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`, если в карте этот ключ отсутствует. **Синтаксис** ```sql theme={null} aiExtract(text, instruction_or_schema[, params]) ``` **Псевдонимы**: `AIExtract` **Аргументы** * `text` — Текст, из которого нужно извлечь информацию. [`String`](/docs/ru/reference/data-types/string) * `instruction_or_schema` — Инструкция для извлечения в свободной форме или константный объект JSON, описывающий извлекаемые поля. [`const String`](/docs/ru/reference/data-types/string) * `params` — Необязательный константный `Map(String, String)` параметров. Ключи, специфичные для функции: `temperature` (температура сэмплирования, определяющая степень случайности; по умолчанию `0.0`), `max_tokens` (максимальное количество выходных токенов на вызов; по умолчанию `1024`). Также применяются общие параметры `credentials` и `model` (см. [функции ИИ](/docs/ru/reference/functions/regular-functions/ai-functions)). [`Map(String, String)`](/docs/ru/reference/data-types/map) **Возвращаемое значение** Одно извлечённое значение (режим инструкции) или строка с объектом JSON (режим схемы). Возвращает значение по умолчанию для типа столбца (пустую строку), если запрос завершился ошибкой и `ai_function_throw_on_error` отключён. [`String`](/docs/ru/reference/data-types/string) **Примеры** **Инструкция в свободной форме** ```sql title=Query theme={null} SELECT aiExtract('The package arrived late and was damaged.', 'the main complaint') ``` ```response title=Response theme={null} late and damaged package ``` **Извлечение схемы** ```sql title=Query theme={null} SELECT aiExtract(review, '{"sentiment": "positive, negative or neutral", "topic": "main topic of the review"}') FROM reviews LIMIT 5 ```
## aiFilter
Добавлено в: v26.8.0 Проверяет условие, заданное на естественном языке, по указанному тексту с помощью провайдера LLM и возвращает булево значение (`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 вызывается один раз для каждой пары кандидатов, что может быть затратно. **Синтаксис** ```sql theme={null} aiFilter(text, condition[, params]) ``` **Псевдонимы**: `AIFilter` **Аргументы** * `text` — Текст для оценки. [`String`](/docs/ru/reference/data-types/string) * `condition` — Постоянное условие на естественном языке, которому должен удовлетворять текст. [`String`](/docs/ru/reference/data-types/string) * `params` — Необязательный постоянный `Map(String, String)` параметров. Специфичные для функции ключи: `temperature` (температура сэмплирования, определяющая случайность; по умолчанию `0.0`), `max_tokens` (максимальное количество выходных токенов за вызов; по умолчанию `1024`). Также применяются общие параметры `credentials` и `model` (см. [функции ИИ](/docs/ru/reference/functions/regular-functions/ai-functions)). [`Map(String, String)`](/docs/ru/reference/data-types/map) **Возвращаемое значение** `1`, если текст соответствует условию, иначе `0`. Возвращает значение по умолчанию (`0`), если запрос завершился ошибкой и `ai_function_throw_on_error` отключён. [`UInt8`](/docs/ru/reference/data-types/int-uint) **Примеры** **Фильтрация гневных отзывов** ```sql title=Query theme={null} SELECT * FROM reviews WHERE aiFilter(body, 'the customer is angry about shipping') ``` **Фильтрация столбца с явно заданными учётными данными** ```sql title=Query theme={null} SELECT body, aiFilter(body, 'describes a bug', map('credentials', 'ai_text_credentials')) AS is_bug FROM issues LIMIT 5 ```
## aiGenerate
Добавленный в: v26.4.0 Генерирует произвольный текст по промпту с помощью провайдера LLM. Функция отправляет промпт настроенному AI-провайдеру и возвращает сгенерированный текст. Учетные данные (именованная коллекция с указанием провайдера, модели, конечной точки и, при необходимости, ключа API) берутся из ключа `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.` **Синтаксис** ```sql theme={null} aiGenerate(prompt[, params]) ``` **Псевдонимы**: `AIGenerate` **Аргументы** * `prompt` — Пользовательский промпт или вопрос, отправляемый модели. [`String`](/docs/ru/reference/data-types/string) * `params` — Необязательный константный `Map(String, String)` с параметрами. Специфичные для функции ключи: `temperature` (температура сэмплирования, управляющая случайностью; по умолчанию `0.7`), `max_tokens` (максимальное число выходных токенов за один вызов; по умолчанию `1024`), `system_prompt` (константная системная инструкция, определяющая поведение модели; по умолчанию — общий промпт ассистента). Также применяются общие параметры `credentials` и `model` (см. [функции ИИ](/docs/ru/reference/functions/regular-functions/ai-functions)). [`Map(String, String)`](/docs/ru/reference/data-types/map) **Возвращаемое значение** Сгенерированный текстовый ответ или значение по умолчанию для типа столбца (пустая строка), если запрос завершился ошибкой и `ai_function_throw_on_error` отключён. [`String`](/docs/ru/reference/data-types/string) **Примеры** **Простой вопрос** ```sql title=Query theme={null} SELECT aiGenerate('What is 2 + 2? Reply with just the number.') ``` ```response title=Response theme={null} 4 ``` **С явными учетными данными и системным промптом** ```sql title=Query theme={null} SELECT aiGenerate('Explain ClickHouse', map('credentials', 'ai_text_credentials', 'system_prompt', 'You are a database expert. Be concise.')) ``` **Сводка значений столбца** ```sql title=Query theme={null} SELECT article_title, aiGenerate(concat('Summarize in one sentence: ', article_body)) AS summary FROM articles LIMIT 5 ```
## aiRedact
Добавлено в: v26.8.0 Обнаруживает и маскирует персональные данные (PII) в заданном тексте с помощью провайдера LLM. `aiRedact` обнаруживает и маскирует PII с помощью LLM в меру своих возможностей, поэтому его вывод ненадёжен. Обнаружение и удаление PII зависят от выбранной модели, промпта и входных данных: модель может пропустить идентификаторы, замаскировать их лишь частично или изменить окружающий текст. Функция лучше всего работает с грамотно составленным английским текстом; для других языков или текста с большим количеством орфографических, пунктуационных или грамматических ошибок результаты могут быть хуже. `aiRedact` не гарантирует отсутствие PII в своём выводе и не должен рассматриваться как самостоятельный безопасный или достаточный механизм анонимизации. Перед передачей данных недоверенным сторонам всегда проверяйте вывод, чтобы убедиться, что он соответствует политикам вашей организации в области конфиденциальности данных и соблюдения нормативных требований. Каждый обнаруженный диапазон PII заменяется токеном маскирования (по умолчанию `[REDACTED]`, настраивается через параметр `replacement`). Массив `categories` ограничивает типы маскируемых PII; пустой массив использует набор распространённых категорий по умолчанию (имя, email, номер телефона, адрес, кредитная карта, IP-адрес). `aiRedact` предписывает модели изменять только обнаруженные диапазоны PII, однако сохранение окружающего текста также выполняется в меру возможностей, поэтому модель всё равно может его изменить (см. предупреждение выше). Управляющие символы, кроме табуляции, перевода строки и возврата каретки, перед отправкой запроса также заменяются пробелами, поэтому вывод не является побайтно идентичным входным данным, содержащим такие символы. Поскольку `aiRedact` возвращает весь входной текст с заменёнными PII, вывод имеет примерно ту же длину, что и входные данные. Установите `max_tokens` (по умолчанию `1024`) выше длины входных данных в токенах; ответ, усечённый из-за слишком низкого ограничения, будет неполным. **Синтаксис** ```sql theme={null} aiRedact(text, categories[, params]) ``` **Псевдонимы**: `AIRedact` **Аргументы** * `text` — Текст для маскирования. [`String`](/docs/ru/reference/data-types/string) * `categories` — Постоянный список категорий PII, подлежащих маскированию (например, `['name', 'ssn', 'credit_card']`). При пустом массиве используется набор распространённых категорий по умолчанию (имя, электронная почта, номер телефона, адрес, кредитная карта, IP-адрес). [`Array(String)`](/docs/ru/reference/data-types/array) * `params` — Необязательный постоянный `Map(String, String)` параметров. Специфичные для функции ключи: `temperature` (температура сэмплирования, управляющая случайностью; по умолчанию `0.0`), `max_tokens` (максимальное количество выходных токенов за вызов; по умолчанию `1024` — поскольку `aiRedact` возвращает полный текст, задайте значение больше длины входного текста в токенах, иначе ответ может быть усечённым и неполным), `replacement` (токен, заменяющий каждый обнаруженный фрагмент PII; по умолчанию `[REDACTED]`). Также применяются общие параметры `credentials` и `model` (см. [Функции ИИ](/docs/ru/reference/functions/regular-functions/ai-functions)). [`Map(String, String)`](/docs/ru/reference/data-types/map) **Возвращаемое значение** Текст, в котором обнаруженные PII заменены токеном маскирования, или значение по умолчанию для типа столбца (пустая строка), если запрос завершился с ошибкой и `ai_function_throw_on_error` отключён. [`String`](/docs/ru/reference/data-types/string) **Примеры** **Маскирование определённых категорий** ```sql title=Query theme={null} SELECT aiRedact('Purchase was done by customer John Doe with email test@test.org', ['email', 'credit_card', 'name']) ``` ```response title=Response theme={null} Purchase was done by customer [REDACTED] with email [REDACTED] ``` **Маскировка категорий PII по умолчанию с помощью пользовательского токена** ```sql title=Query theme={null} SELECT aiRedact(body, [], map('replacement', '***')) FROM tickets LIMIT 5 ```
## aiSimilarity
Добавлено в: v26.8.0 Вычисляет семантическое сходство двух текстов с помощью настроенного провайдера эмбеддингов. Вычисляет векторные эмбеддинги обоих текстов и возвращает их [косинусное сходство](https://en.wikipedia.org/wiki/Cosine_similarity). Оценка `-1` присваивается противоположным векторам эмбеддингов; семантически это означает, что тексты с оценками, близкими к `-1`, противоположны по смыслу. Оценка `0` означает, что векторы ортогональны, то есть семантически не связаны. Наконец, оценка `1` означает, что векторы эмбеддингов направлены в одну сторону, а тексты с оценками, близкими к `1`, схожи по смыслу. Это дополнение `cosineDistance` для тех же эмбеддингов (`aiSimilarity = 1 - cosineDistance(embedding1, embedding2)`). Батчинг, учетные данные и параметр `dimensions` соответствуют `aiEmbed`, включая настройку учетных данных по умолчанию `ai_function_embedding_default_credentials`. Как и в `aiEmbed`, `model` — обязательный позиционный аргумент (константный `String`), который не считывается из именованной коллекции или карты параметров. **Синтаксис** ```sql theme={null} aiSimilarity(text1, text2, model[, params]) ``` **Псевдонимы**: `AISimilarity` **Аргументы** * `text1` — Первый текст. [`String`](/docs/ru/reference/data-types/string) * `text2` — Второй текст. [`String`](/docs/ru/reference/data-types/string) * `model` — Имя модели эмбеддингов. [`const String`](/docs/ru/reference/data-types/string) * `params` — Необязательный константный `Map(String, String)` параметров. Ключ, специфичный для этой функции: `dimensions` (целевая размерность эмбеддингов; `0` или отсутствие значения означает собственную размерность модели). Также применяется общий параметр `credentials` (см. [функции ИИ](/docs/ru/reference/functions/regular-functions/ai-functions)). [`Map(String, String)`](/docs/ru/reference/data-types/map) **Возвращаемое значение** Косинусное сходство в диапазоне `[-1, 1]` или NULL, если один из текстов имеет значение NULL или пуст, запрос на создание эмбеддинга завершился ошибкой при отключённом `ai_function_throw_on_error` либо квота была превышена при отключённом `ai_function_throw_on_quota_exceeded`. [`Nullable(Float32)`](/docs/ru/reference/data-types/nullable) **Примеры** **Сравнение двух строк (`credentials` можно не указывать, если задана настройка `ai_function_embedding_default_credentials`)** ```sql title=Query theme={null} SELECT aiSimilarity('cat', 'kitten', 'text-embedding-3-small', map('credentials', 'ai_embedding_credentials')) ``` **Ранжируйте отзывы по схожести с запросом** ```sql title=Query theme={null} SELECT review FROM product_reviews ORDER BY aiSimilarity(review, 'It works well under rain', 'text-embedding-3-small') DESC LIMIT 100 ``` **Семантическая дедупликация с использованием self-join** ```sql title=Query theme={null} SELECT a.id, b.id FROM docs a, docs b WHERE a.id < b.id AND aiSimilarity(a.title, b.title, 'text-embedding-3-small') > 0.9 ```
## aiTranslate
Добавленный в: v26.4.0 Переводит заданный текст на указанный целевой язык с помощью провайдера LLM. Дополнительные указания по стилю или диалекту можно передать через ключ `instructions` в карте параметров (например, `'keep technical terms untranslated'`). Учетные данные (именованная коллекция, задающая провайдера, модель, конечную точку и, при необходимости, ключ API) берутся из ключа `credentials` необязательной карты параметров или из настройки `ai_function_text_default_credentials`, если в карте этот ключ отсутствует. **Синтаксис** ```sql theme={null} aiTranslate(text, target_language[, params]) ``` **Псевдонимы**: `AITranslate` **Аргументы** * `text` — Текст для перевода. [`String`](/docs/ru/reference/data-types/string) * `target_language` — Название целевого языка или код BCP-47 (например, `'French'`, `'es-MX'`). [`String`](/docs/ru/reference/data-types/string) * `params` — Необязательная константа `Map(String, String)` с параметрами. Ключи, специфичные для этой функции: `temperature` (температура сэмплирования, определяющая случайность; по умолчанию `0.3`), `max_tokens` (максимальное количество выходных токенов за один вызов; по умолчанию `1024`), `instructions` (дополнительные указания по стилю или диалекту для переводчика). Также применяются общие параметры `credentials` и `model` (см. [Функции ИИ](/docs/ru/reference/functions/regular-functions/ai-functions)). [`Map(String, String)`](/docs/ru/reference/data-types/map) **Возвращаемое значение** Переведённый текст или значение по умолчанию для типа столбца (пустая строка), если запрос завершился ошибкой и `ai_function_throw_on_error` отключён. [`String`](/docs/ru/reference/data-types/string) **Примеры** **Перевод на французский** ```sql title=Query theme={null} SELECT aiTranslate('Hello, world!', 'French') ``` ```response title=Response theme={null} Bonjour le monde! ``` **Перевести на японский с учетом инструкций по стилю** ```sql title=Query theme={null} SELECT aiTranslate(body, 'Japanese', map('instructions', 'Use polite form (desu/masu)')) FROM articles LIMIT 5 ```