> ## Documentation Index
> Fetch the complete documentation index at: https://private-7c7dfe99-fix-nav-issues.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

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

# Функции ИИ

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

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

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

* **Контроль квот**: лимиты на количество токенов в рамках одного запроса ([`ai_function_max_input_tokens_per_query`](/ru/reference/settings/session-settings#ai_function_max_input_tokens_per_query), [`ai_function_max_output_tokens_per_query`](/ru/reference/settings/session-settings#ai_function_max_output_tokens_per_query)) и вызовов API ([`ai_function_max_api_calls_per_query`](/ru/reference/settings/session-settings#ai_function_max_api_calls_per_query)).
* **Повторные попытки с задержкой**: при временных сбоях выполняются повторные попытки ([`ai_function_max_retries`](/ru/reference/settings/session-settings#ai_function_max_retries)) с экспоненциально растущей задержкой ([`ai_function_retry_initial_delay_ms`](/ru/reference/settings/session-settings#ai_function_retry_initial_delay_ms)).

<div id="configuration">
  ## Конфигурация
</div>

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

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

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

<div id="named-collection-parameters">
  ### Параметры именованной коллекции
</div>

| Параметр      | Тип    | По умолчанию | Описание                                                                          |
| ------------- | ------ | ------------ | --------------------------------------------------------------------------------- |
| `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'`).                     |

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

<div id="query-level-settings">
  ### Настройки на уровне запроса
</div>

Все настройки, связанные с ИИ, перечислены в разделе [Настройки](/ru/reference/settings/session-settings) и имеют префикс `ai_function_`.

<div id="restricting-endpoint-hosts">
  ### Ограничение хостов конечных точек
</div>

URL `endpoint` в именованной коллекции AI — это исходящий пункт назначения, к которому сервер подключается от своего имени, передавая `api_key` этой именованной коллекции в заголовках запроса. По умолчанию ClickHouse разрешает любой хост. Чтобы ограничить функции определённым набором провайдеров, настройте [`remote_url_allow_hosts`](/ru/reference/settings/server-settings/settings#remote_url_allow_hosts) в конфигурации сервера, например:

```xml theme={null}
<remote_url_allow_hosts>
    <host>api.openai.com</host>
    <host>api.anthropic.com</host>
</remote_url_allow_hosts>
```

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

<div id="supported-providers">
  ## Поддерживаемые провайдеры
</div>

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

<div id="observability">
  ## Обсервабилити
</div>

Активность функции ИИ отслеживается через ClickHouse [ProfileEvents](/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;
```

{/*AUTOGENERATED_START*/}

<div id="aiClassify">
  ## aiClassify
</div>

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

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

Функция отправляет текст вместе с фиксированным промптом для классификации и форматом ответа в виде JSON Schema, который ограничивает модель так, чтобы она возвращала ровно одну из переданных меток. Если ответ возвращается как JSON-объект вида `{"category": "..."}`, метка извлекается, и функция возвращает строку этой метки.

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

**Синтаксис**

```sql theme={null}
aiClassify(collection, text, categories[, temperature])
```

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

**Аргументы**

* `collection` — Имя именованной коллекции, содержащей учетные данные провайдера и конфигурацию. [`String`](/ru/reference/data-types/string)
* `text` — Текст для классификации. [`String`](/ru/reference/data-types/string)
* `categories` — Константный список возможных меток категорий. [`Array(String)`](/ru/reference/data-types/array)
* `temperature` — Температура сэмплирования, влияющая на случайность. По умолчанию: `0.0`. [`Float64`](/ru/reference/data-types/float)

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

Одна из указанных меток категорий или значение по умолчанию для типа столбца (пустая строка), если при запросе произошла ошибка и `ai_function_throw_on_error` отключен. [`String`](/ru/reference/data-types/string)

**Примеры**

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

```sql title=Query theme={null}
SELECT aiClassify('ai_credentials', 'I love this product!', ['positive', 'negative', 'neutral'])
```

```response title=Response theme={null}
positive
```

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

```sql title=Query theme={null}
SELECT body, aiClassify('ai_credentials', body, ['bug', 'question', 'feature']) AS kind FROM issues LIMIT 5
```

```response title=Response theme={null}
```

<div id="aiExtract">
  ## aiExtract
</div>

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

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

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

В режиме инструкции функция возвращает извлечённое значение в виде обычной строки или пустую строку, если ничего не найдено.
В режиме схемы функция возвращает строку с объектом JSON, ключи которого соответствуют запрошенной схеме; отсутствующие поля имеют значение `null`.

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

**Синтаксис**

```sql theme={null}
aiExtract(collection, text, instruction_or_schema[, temperature])
```

**Псевдонимы**: `AIExtract`

**Аргументы**

* `collection` — Имя именованной коллекции, содержащей учетные данные провайдера и конфигурацию. [`String`](/ru/reference/data-types/string)
* `text` — Текст, из которого нужно извлечь информацию. [`String`](/ru/reference/data-types/string)
* `instruction_or_schema` — Инструкция для извлечения в свободной форме или константный объект JSON, описывающий извлекаемые поля. [`const String`](/ru/reference/data-types/string)
* `temperature` — Температура сэмплирования, определяющая степень случайности. По умолчанию: `0.0`. [`const Float64`](/ru/reference/data-types/float)

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

Одно извлечённое значение (режим инструкции) или строка с объектом JSON (режим схемы). Возвращает значение по умолчанию для типа столбца (пустую строку), если запрос завершился ошибкой и `ai_function_throw_on_error` отключён. [`String`](/ru/reference/data-types/string)

**Примеры**

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

```sql title=Query theme={null}
SELECT aiExtract('ai_credentials', '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('ai_credentials', review, '{"sentiment": "positive, negative or neutral", "topic": "main topic of the review"}') FROM reviews LIMIT 5
```

```response title=Response theme={null}
```

<div id="aiGenerate">
  ## aiGenerate
</div>

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

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

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

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

**Синтаксис**

```sql theme={null}
aiGenerate(collection, prompt[, system_prompt[, temperature]])
```

**Псевдонимы**: `AIGenerate`

**Аргументы**

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

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

Сгенерированный текстовый ответ или значение по умолчанию для типа столбца (пустая строка), если запрос завершился ошибкой и `ai_function_throw_on_error` отключён. [`String`](/ru/reference/data-types/string)

**Примеры**

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

```sql title=Query theme={null}
SELECT aiGenerate('ai_credentials', 'What is 2 + 2? Reply with just the number.')
```

```response title=Response theme={null}
4
```

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

```sql title=Query theme={null}
SELECT aiGenerate('ai_credentials', 'Explain ClickHouse', 'You are a database expert. Be concise.')
```

```response title=Response theme={null}
```

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

```sql title=Query theme={null}
SELECT article_title, aiGenerate('ai_credentials', concat('Summarize in one sentence: ', article_body)) AS summary FROM articles LIMIT 5
```

```response title=Response theme={null}
```

<div id="aiTranslate">
  ## aiTranslate
</div>

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

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

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

Первый аргумент — именованная коллекция, в которой указаны провайдер, модель, конечная точка и ключ API.

**Синтаксис**

```sql theme={null}
aiTranslate(collection, text, target_language[, instructions[, temperature]])
```

**Псевдонимы**: `AITranslate`

**Аргументы**

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

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

Переведённый текст или значение по умолчанию для типа столбца (пустая строка), если запрос завершился ошибкой и `ai_function_throw_on_error` отключён. [`String`](/ru/reference/data-types/string)

**Примеры**

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

```sql title=Query theme={null}
SELECT aiTranslate('ai_credentials', 'Hello, world!', 'French')
```

```response title=Response theme={null}
Bonjour le monde!
```

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

```sql title=Query theme={null}
SELECT aiTranslate('ai_credentials', body, 'Japanese', 'Use polite form (desu/masu)') FROM articles LIMIT 5
```

```response title=Response theme={null}
```