--- metadata: - name: generator content: Diplodoc Platform v5.12.4 alternate: - https://yandex.ru/support/cloudai-hybrid/ru/usage.md --- > **Documentation Index:** Fetch the complete configuration index at https://yandex.ru/support/cloudai-hybrid/ru/llms.txt # Эксплуатация программного обеспечения Cloud AI Hybrid Для эксплуатации Cloud AI Hybrid необходимо выполнять запросы в программный интерфейс ПО (API), используя один из доступных интерфейсов (REST или gRPC). ## API генерации текста, REST {#rest-api} Метод для генерации дополнений текста в синхронном режиме. ### HTTP-запрос {#http-request} ``` POST /foundationModels/v1/completion ``` ### Параметры тела запроса {#request-body} ```json { "modelUri": "string", "completionOptions": { "stream": "boolean", "temperature": "number", "maxTokens": "string" }, "messages": [ { "role": "string", "text": "string" } ] } ``` Запрос на генерацию дополнения текста. #| || **Поле** | **Описание** || || modelUri | **string** ID модели, которая будет использоваться для генерации дополнения. || || completionOptions | **CompletionOptions** Параметры конфигурации для генерации дополнений. || || messages\[\] | **Message** Список сообщений, представляющих контекст для модели дополнений. || |# #### CompletionOptions {#completion-options} Определяет параметры для генерации дополнений. #| || **Поле** | **Описание** || || stream | **boolean** Включает потоковую передачу частично сгенерированного текста. || || temperature | **number** (double) Влияет на креативность и случайность ответов. Должен быть числом с плавающей запятой от 0 (включительно) до 1 (включительно). Низкие значения приводят к более прямолинейным ответам, в то время как высокие значения увеличивают креативность и случайность. По умолчанию температура: 0.3 || || maxTokens | **string** (int64) Ограничение на количество токенов, используемых для одного дополнения. Должно быть больше нуля. Это максимальное значение может зависеть от используемой модели. || |# #### Message {#message} Объект сообщения, представляющий оболочку для входных и выходных данных модели дополнений. #| || **Поле** | **Описание** || || role | **string** ID отправителя сообщения. Поддерживаемые роли: * `system`: Специальная роль, используемая для определения поведения модели дополнений. * `assistant`: Роль, используемая моделью для генерации ответов. * `user`: Роль, используемая пользователем для описания запросов к модели. || || text | **string** Текстовое содержание сообщения. || |# ### Response {#response} **HTTP Код: 200 - OK** ```json { "alternatives": [ { "message": { "role": "string", "text": "string" }, "status": "string" } ], "usage": { "inputTextTokens": "string", "completionTokens": "string", "totalTokens": "string" }, "modelVersion": "string" } ``` Ответ, содержащий сгенерированные дополнения текста. #| || **Поле** | **Описание** || || alternatives\[\] | **Alternative** Список альтернативных дополнений. || || usage | **ContentUsage** Набор статистических данных, описывающих количество использованных токенов контента моделью дополнений. || || modelVersion | **string** Версия модели, которая изменяется с каждым новым выпуском. || |# #### Alternative {#alternative} Представляет альтернативу сгенерированного дополнения, включая его содержание и статус генерации. #| || **Поле** | **Описание** || || message | **Message** Сообщение с содержанием альтернативы. || || status | **enum** (AlternativeStatus) Статус генерации альтернативы. - `ALTERNATIVE_STATUS_UNSPECIFIED`: Неопределенный статус генерации. - `ALTERNATIVE_STATUS_PARTIAL`: Частично сгенерированная альтернатива. - `ALTERNATIVE_STATUS_TRUNCATED_FINAL`: Некомплетная финальная альтернатива, полученная из-за достижения максимального допустимого числа токенов. - `ALTERNATIVE_STATUS_FINAL`: Финальная альтернатива, сгенерированная без достижения лимита. || |# #### Message {#response-message} Объект сообщения, представляющий оболочку для входных и выходных данных модели дополнений. #| || **Поле** | **Описание** || || role | **string** ID отправителя сообщения. Поддерживаемые роли: * `system`: Специальная роль, используемая для определения поведения модели дополнений. * `assistant`: Роль, используемая моделью для генерации ответов. * `user`: Роль, используемая пользователем для описания запросов к модели. || || text | **string** Текстовое содержание сообщения. Содержание сообщения. || |# #### ContentUsage {#content-usage} Объект, представляющий количество токенов контента, использованных моделью дополнений. #| || **Поле** | **Описание** || || inputTextTokens | **string** (int64) Количество токенов в текстовой части входных данных модели. || || completionTokens | **string** (int64) Количество токенов в сгенерированном дополнении. || || totalTokens | **string** (int64) Общее количество токенов, включая все входные и сгенерированные токены. || |# ## API генерации текста, gRPC {#grpc-api} Метод для генерации дополнений текста в синхронном режиме. ### gRPC-запрос {#grpc-request} **rpc Completion (CompletionRequest) returns (stream CompletionResponse)** ### CompletionRequest {#completion-request} ```json { "model_uri": "string", "completion_options": { "stream": "bool", "temperature": "google.protobuf.DoubleValue", "max_tokens": "google.protobuf.Int64Value" }, "messages": [ { "role": "string", "text": "string", } ] } ``` Запрос к сервису для генерации дополнений текста. #| || **Поле** | **Описание** || || model\_uri | **string** Идентификатор модели, которая будет использоваться для генерации дополнений. || || completion\_options | **CompletionOptions** Настройки для генерации дополнений. || || messages\[\] | **Message** Список сообщений, представляющих контекст для модели дополнений. || |# #### CompletionOptions {#completion-options-grpc} Определяет параметры для генерации дополнений. #| || **Поле** | **Описание** || || stream | **bool** Включает потоковую передачу частично сгенерированного текста. || || temperature | **google.protobuf.DoubleValue** Влияет на креативность и случайность ответов. Должно быть числом с плавающей точкой от 0 (включительно) до 1 (включительно). Меньшие значения приводят к более прямолинейным ответам, в то время как более высокие значения увеличивают креативность и случайность. По умолчанию температура: 0.3 || || max\_tokens | **google.protobuf.Int64Value** Ограничение на количество токенов, используемых для одного дополнения. Должно быть больше нуля. Это максимальное значение может зависеть от используемой модели. || |# #### Message {#grpc-request-message} Объект сообщения, представляющий оболочку для входных и выходных данных модели дополнений. #| || **Поле** | **Описание** || || role | **string** Идентификатор отправителя сообщения. Поддерживаемые роли: * `system`: Специальная роль, используемая для определения поведения модели дополнений. * `assistant`: Роль, используемая моделью для генерации ответов. * `user`: Роль, используемая пользователем для описания запросов модели. || || text | **string** Текстовое содержание сообщения. || |# ### CompletionResponse {#grpc-response} ```json { "alternatives": [ { "message": { "role": "string", "text": "string" }, "status": "AlternativeStatus" } ], "usage": { "input_text_tokens": "int64", "completion_tokens": "int64", "total_tokens": "int64" }, "model_version": "string" } ``` Ответ, содержащий сгенерированные дополнения текста. #| || **Поле** | **Описание** || || alternatives\[\] | **Alternative** Список сгенерированных альтернатив дополнений. || || usage | **ContentUsage** Набор статистики, описывающий количество токенов контента, использованных моделью дополнений. || || model\_version | **string** Версия модели, которая изменяется с каждым новым релизом. || |# #### Alternative {#grpc-alternative} Представляет сгенерированную альтернативу дополнения, включая ее содержание и статус генерации. #| || **Поле** | **Описание** || || message | **Message** Сообщение с содержанием альтернативы. || || status | enum **AlternativeStatus** Статус генерации альтернативы. - `ALTERNATIVE_STATUS_UNSPECIFIED`: Неуказанный статус генерации. - `ALTERNATIVE_STATUS_PARTIAL`: Частично сгенерированная альтернатива. - `ALTERNATIVE_STATUS_TRUNCATED_FINAL`: Неполная финальная альтернатива, результат из-за достижения максимального допустимого числа токенов. - `ALTERNATIVE_STATUS_FINAL`: Финальная альтернатива, сгенерированная без достижения каких-либо ограничений. || |# #### Message {#grpc-response-message} Объект сообщения, представляющий оболочку для входных и выходных данных модели дополнений. #| || **Поле** | **Описание** || || role | **string** Идентификатор отправителя сообщения. Поддерживаемые роли: * `system`: Специальная роль, используемая для определения поведения модели дополнений. * `assistant`: Роль, используемая моделью для генерации ответов. * `user`: Роль, используемая пользователем для описания запросов модели. || || text | **string** Текстовое содержание сообщения. || |# #### ContentUsage {#grpc-content-usage} Объект, представляющий количество токенов контента, использованных моделью дополнений. #| || **Поле** | **Описание** || || input\_text\_tokens | **int64** Количество токенов в текстовой части входных данных модели. || || completion\_tokens | **int64** Количество токенов в сгенерированном дополнении. || || total\_tokens | **int64** Общее количество токенов, включая все входные токены и все сгенерированные токены. || |# ## API векторизации текста, REST {#rest-embeddings} Метод получения эмбеддингов из текстовых данных. ### HTTP-запрос {#rest-embeddings-request} ``` POST /foundationModels/v1/textEmbedding ``` ### Параметры тела {#rest-embeddings-body} ```json { "modelUri": "string", "text": "string" } ``` Запрос к сервису для получения эмбеддингов текста. #| || **Поле** | **Описание** || || modelUri | **строка** URI модели, которая будет использоваться для получения эмбеддингов текста. || || text | **строка** Входной текст, для которого запрашивается эмбеддинг. || |# ### Ответ {#rest-embeddings-response} **HTTP Код: 200 - OK** ```json { "embedding": [ "string" ], "numTokens": "string", "modelVersion": "string" } ``` Ответ, содержащий сгенерированный эмбеддинг текста. #| || **Поле** | **Описание** || || embedding\[\] | **строка** Повторяющийся список значений с плавающей запятой, представляющих эмбеддинг. || || numTokens | **строка** (int64) Количество токенов во входном тексте. || || modelVersion | **строка** Версия модели, которая изменяется с каждым новым релизом. || |# ## API для векторизации текста, gRPC {#grpc-embeddings} Метод для получения эмбеддингов из текстовых данных. ### gRPC-запрос {#grpc-embeddings-request} **rpc TextEmbedding (TextEmbeddingRequest) returns (TextEmbeddingResponse)** ### TextEmbeddingRequest {#grpc-embeddings-body} ```json { "model_uri": "string", "text": "string" } ``` Запрос к сервису для получения эмбеддингов текста. #| || **Поле** | **Описание** || || model\_uri | **string** URI модели, который будет использоваться для получения эмбеддингов текста. || || text | **string** Входной текст, для которого запрашиваются эмбеддинги. || |# ## TextEmbeddingResponse {#grpc-embeddings-response} ```json { "embedding": [ "double" ], "num_tokens": "int64", "model_version": "string" } ``` Ответ, содержащий сгенерированный эмбеддинг текста. #| || **Поле** | **Описание** || || embedding\[\] | **double** Повторяющийся список значений типа double, представляющих эмбеддинг. || || num\_tokens | **int64** Количество токенов во входном тексте. || || model\_version | **string** Версия модели, которая изменяется с каждым новым релизом. || |# ## API для классификации текста, REST {#rest-classifier} Метод для бинарной и многоклассовой классификации. Вы можете предоставить до 20 классов для классификации текста с малым количеством примеров. ### HTTP-запрос {#rest-classifier-request} ``` POST /foundationModels/v1/fewShotTextClassification ``` ### Параметры тела запроса {#rest-classifier-body} ```json { "modelUri": "string", "taskDescription": "string", "labels": [ "string" ], "text": "string", "samples": [ { "text": "string", "label": "string" } ] } ``` Запрос для классификации текста. #| || **Поле** | **Описание** || || modelUri | **string** URI модели классификатора. || || taskDescription | **string** Текстовое описание задачи классификации. || || labels\[\] | **string** Список доступных меток для результата классификации. Дайте значимые имена классам меток: это важно для правильных результатов классификации. Например, используйте `химия` и `физика` вместо `хим` и `физ` для названий классов. || || text | **string** Текст для классификации. || || samples\[\] | **ClassificationSample** Необязательный набор образцов текста с ожидаемыми метками, которые могут быть использованы в качестве дополнительной подсказки для классификатора. || |# #### ClassificationSample {#rest-classifier-sample} Описание образца для задачи классификации. #| || **Поле** | **Описание** || || text | **string** Образец текста. || || label | **string** Ожидаемая метка для данного текста. || |# ### Ответ {#rest-classifier-request} **HTTP код: 200 - OK** ```json { "predictions": [ { "label": "string", "confidence": "string" } ], "modelVersion": "string" } ``` Ответ, содержащий предсказания классификатора. #| || **Поле** | **Описание** || || predictions\[\] | **ClassificationLabel** Результаты классификации с значениями `confidence` для вероятности того, что текст запроса будет отнесен к каждому классу. || || modelVersion | **string** Версия модели, которая изменяется с каждым новым выпуском. || |# #### ClassificationLabel {#rest-classifier-label} Пара текстовых меток и их соответствующих значений доверия. #| || **Поле** | **Описание** || || label | **string** Метка названия класса. || || confidence | **string** Вероятность того, что текст будет отнесен к определенному классу. || |# ## API для классификации текста, gRPC {#grpc-classifier} gRPC-метод для бинарной и многоклассовой классификации. Вы можете предоставить до 20 классов для классификации текста с несколькими примерами. ### Запрос gRPC {#grpc-classifier-request} **rpc FewShotClassify (FewShotTextClassificationRequest) returns (FewShotTextClassificationResponse)** ### FewShotTextClassificationRequest {#grpc-classifier-body} ```json { "model_uri": "string", "task_description": "string", "labels": [ "string" ], "text": "string", "samples": [ { "text": "string", "label": "string" } ] } ``` Запрос на классификацию текста сервисом. #| || **Поле** | **Описание** || || model\_uri | **string** URI модели классификатора. || || task\_description | **string** Текстовое описание задачи классификации. || || labels\[\] | **string** Список доступных меток для классификации. Дайте меткам осмысленные имена: это важно для корректных результатов классификации. Например, используйте `химия` и `физика` вместо `хим` и `физ` для имен классов. || || text | **string** Текст для классификации. || || samples\[\] | **ClassificationSample** Необязательный набор текстовых примеров с ожидаемыми метками, которые могут быть использованы как дополнительная подсказка для классификатора. || |# #### ClassificationSample {#grpc-classifier-sample} Описание примера для задачи классификации. #| || **Поле** | **Описание** || || text | **string** Текстовый пример. || || label | **string** Ожидаемая метка для данного текста. || |# ### FewShotTextClassificationResponse {#grpc-classifier-response} ```json { "predictions": [ { "label": "string", "confidence": "double" } ], "model_version": "string" } ``` Ответ, содержащий прогнозы классификатора. #| || **Поле** | **Описание** || || predictions\[\] | **ClassificationLabel** Результаты классификации с значениями `confidence`, которые представляют вероятность классификации текста запроса в каждый из классов. || || model\_version | **string** Версия модели изменяется с каждым новым выпуском. || |# #### ClassificationLabel {#grpc-classifier-label} Пара меток текста и их соответствующих значений уверенности. #| || **Поле** | **Описание** || || label | **string** Метка класса. || || confidence | **double** Вероятность классификации текста в конкретный класс. || |#   ## Пример выполнения запроса в интерфейс REST с помощью cURL {#rest-example} ### Отправка REST-запроса {#rest-request} ```bash curl \ --http1.0 \ --request POST \ "http://:8080/foundationModels/v1/completion" \ --header "Content-Type: application/json; charset=utf-8" \ --header "Authorization: Bearer 0" \ --data @- <<'EOF' { "modelUri": "gpt://0/general", "completionOptions": { "stream": false, "temperature": 0.1, "maxTokens": "1000" }, "messages": [ { "role": "system", "text": "Translate text" }, { "role": "user", "text": "To be, or not to be: that is the question." } ] } EOF ``` ### Результат {#result} ```text {"result":{"alternatives":[{"message":{"role":"assistant","text":"Быть или не быть — вот в чём вопрос."},"status":"ALTERNATIVE_STATUS_FINAL"}],"usage":{"inputTextTokens":"26","completionTokens":"11","totalTokens":"37"},"modelVersion":"07.03.2024"}} ```