Отправить запрос в промт-режиме

Статья создана

Обновлена 18 марта 2025 г.

Перед началом работы
Запрос к модели через REST API
Запрос к модели через gRPC API
- Потоковый запрос через gRPC API

Чтобы сгенерировать текст в промт-режиме, отправьте запрос к модели с помощью метода completion или Yandex Cloud ML SDK.

Перед началом работы

SDK

cURL

Python

Чтобы воспользоваться примерами запросов с использованием SDK:

Создайте сервисный аккаунт и назначьте ему роль ai.languageModels.user.
Получите и сохраните API-ключ сервисного аккаунта.

В примерах используется аутентификация с помощью API-ключа. Yandex Cloud ML SDK также поддерживает аутентификацию с помощью IAM-токена и OAuth-токена. Подробнее см. в разделе Аутентификация в Yandex Cloud ML SDK.
С помощью менеджера пакетов pip установите библиотеку ML SDK:
```
pip install yandex-cloud-ml-sdk
```

Получите данные для аутентификации в API, как описано в разделе Аутентификация в API Yandex Foundation Models.

Чтобы воспользоваться примерами, установите cURL.

Получите данные для аутентификации в API, как описано в разделе Аутентификация в API Yandex Foundation Models.

Запрос к модели через REST API

cURL

Python

Пример ниже разработан для выполнения в операционных системах MacOS и Linux. Чтобы выполнить его в системе Windows, ознакомьтесь с особенностями работы с Bash в Microsoft Windows.

Создайте файл с телом запроса (например, body.json):
```
{
  "modelUri": "gpt://<идентификатор_каталога>/yandexgpt",
  "completionOptions": {
    "stream": false,
    "temperature": 0.1,
    "maxTokens": "1000",
    "reasoningOptions": {
      "mode": "DISABLED"
    }
  },
  "messages": [
    {
      "role": "system",
      "text": "Переведи текст"
    },
    {
      "role": "user",
      "text": "To be, or not to be: that is the question."
    }
  ]
}
```
Где:
- modelUri — идентификатор модели, которая будет использоваться для генерации ответа. Параметр содержит идентификатор каталога Yandex Cloud или идентификатор дообученной модели.
- completionOptions — параметры конфигурации запроса:
  - stream — включает потоковую передачу частично сгенерированного текста. Принимает значения true или false.
  - temperature — чем выше значение этого параметра, тем более креативными и случайными будут ответы модели. Принимает значения от 0 (включительно) до 1 (включительно). Значение по умолчанию: 0.3.
  - maxTokens — устанавливает ограничение на выход модели в токенах. Максимальное число токенов генерации зависит от модели. Подробнее см. в разделе Квоты и лимиты в Yandex Foundation Models.
  - reasoningOptions.mode — параметры режима рассуждений. Необязательный параметр. Значение по умолчанию — DISABLED. Возможные значения:
    - DISABLED — режим рассуждений выключен.
    - ENABLED_HIDDEN — режим рассуждений включен. При этом модель самостоятельно принимает решение о необходимости использования этого режима для каждого конкретного запроса.
- messages — массив сообщений, которые задают контекст для модели:
  - role — роль отправителя сообщения:
    - user — предназначена для отправки пользовательских сообщений к модели.
    - system — позволяет задать контекст запроса и определить поведение модели.
    - assistant — используется для ответов, которые генерирует модель. При работе в режиме чата ответы модели, помеченные ролью assistant, включаются в состав сообщения для сохранения контекста беседы. Не передавайте сообщения пользователя с этой ролью.
  - text — текстовое содержимое сообщения.

Отправьте запрос к модели, выполнив команду:

export FOLDER_ID=<идентификатор_каталога>
export IAM_TOKEN=<IAM-токен>
curl \
  --request POST \
  --header "Content-Type: application/json" \
  --header "Authorization: Bearer ${IAM_TOKEN}" \
  --header "x-folder-id: ${FOLDER_ID}" \
  --data "@<путь_до_файла_json>" \
  "https://llm.api.cloud.yandex.net/foundationModels/v1/completion"

Где:

FOLDER_ID— идентификатор каталога, на который у вашего аккаунта есть роль ai.languageModels.user или выше.
IAM_TOKEN — IAM-токен, полученный перед началом работы.

Результат:

{
  "result": {
    "alternatives": [
      {
        "message": {
          "role": "assistant",
          "text": "Быть или не быть - вот в чём вопрос."
        },
        "status": "ALTERNATIVE_STATUS_FINAL"
      }
    ],
    "usage": {
      "inputTextTokens": "28",
      "completionTokens": "10",
      "totalTokens": "38"
    },
    "modelVersion": "06.12.2023"
  }
}

Создайте файл test.py с кодом запроса к модели:

import requests
import argparse

URL = "https://llm.api.cloud.yandex.net/foundationModels/v1/completion"

def run(iam_token, folder_id, user_text):    
    # Собираем запрос
    data = {}
    # Указываем тип модели
    data["modelUri"] = f"gpt://{folder_id}/yandexgpt"
    # Настраиваем опции
    data["completionOptions"] = {"temperature": 0.3, "maxTokens": 1000}
    # Указываем контекст для модели
    data["messages"] = [
        {"role": "system", "text": "Исправь ошибки в тексте."},
        {"role": "user", "text": f"{user_text}"},
    ]
    
    # Отправляем запрос
    response = requests.post(
        URL,
        headers={
            "Accept": "application/json",
            "Authorization": f"Bearer {iam_token}"
        },
        json=data,
    ).json()

    #Распечатываем результат
    print(response)

if __name__ == '__main__':
    parser = argparse.ArgumentParser()
    parser.add_argument("--iam_token", required=True, help="IAM token")
    parser.add_argument("--folder_id", required=True, help="Folder id")
    parser.add_argument("--user_text", required=True, help="User text")
    args = parser.parse_args()
    run(args.iam_token, args.folder_id, args.user_text)

Запустите файл test.py, подставив значение IAM-токена и идентификатор каталога:

export IAM_TOKEN=<IAM-токен>
export FOLDER_ID=<идентификатор_каталога>
export TEXT='Ашипки саме сибя ни исрпвят'
python test.py \
  --iam_token ${IAM_TOKEN} \
  --folder_id ${FOLDER_ID} \
  --user_text ${TEXT}

Результат:

{'result': {'alternatives': [{'message': {'role': 'assistant', 'text': 'Ошибки сами себя не исправят.'}, 'status': 'ALTERNATIVE_STATUS_FINAL'}], 'usage': {'inputTextTokens': '29', 'completionTokens': '9', 'totalTokens': '38'}, 'modelVersion': '07.03.2024'}}

Запрос к модели через gRPC API

SDK

Python

Создайте файл generate-text.py и добавьте в него следующий код:
```
#!/usr/bin/env python3

from __future__ import annotations
from yandex_cloud_ml_sdk import YCloudML

messages = [
    {
        "role": "system",
        "text": "Найди ошибки в тексте и исправь их",
    },
    {
        "role": "user",
        "text": """Ламинат подойдет для укладке на кухне или в детской 
комнате – он не боиться влаги и механических повреждений благодаря 
защитному слою из облицованных меламиновых пленок толщиной 0,2 мм и 
обработанным воском замкам.""",
    },
]


def main():
    sdk = YCloudML(
        folder_id="<идентификатор_каталога>",
        auth="<API-ключ>",
    )

    result = (
        sdk.models.completions("yandexgpt").configure(temperature=0.5).run(messages)
    )

    for alternative in result:
        print(alternative)


if __name__ == "__main__":
    main()
```
Где:

Примечание

В качестве входных данных для запроса Yandex Cloud ML SDK может принимать строку, словарь, объект класса TextMessage или массив, содержащий любое сочетание указанных типов данных. Подробнее см. в разделе Использование Yandex Cloud ML SDK.
- messages — массив сообщений, которые задают контекст для модели:
  - role — роль отправителя сообщения:
    - user — предназначена для отправки пользовательских сообщений к модели.
    - system — позволяет задать контекст запроса и определить поведение модели.
    - assistant — используется для ответов, которые генерирует модель. При работе в режиме чата ответы модели, помеченные ролью assistant, включаются в состав сообщения для сохранения контекста беседы. Не передавайте сообщения пользователя с этой ролью.
  - text — текстовое содержимое сообщения.
- <идентификатор_каталога> — идентификатор каталога, в котором создан сервисный аккаунт.
- <API-ключ> — API-ключ сервисного аккаунта, полученный ранее и необходимый для аутентификации в API.
  
  В примерах используется аутентификация с помощью API-ключа. Yandex Cloud ML SDK также поддерживает аутентификацию с помощью IAM-токена и OAuth-токена. Подробнее см. в разделе Аутентификация в Yandex Cloud ML SDK.
Подробнее о том, как обращаться к определенной версии модели, см. в разделе Обращение к моделям.

Выполните созданный файл:

python3 generate-text.py

Результат выполнения:

Alternative(role='assistant', text='Ламинат подойдёт для укладки на кухне или в детской комнате. Он не боится влаги и механических повреждений благодаря защитному слою из облицованных меламиновых плёнок толщиной 0,2 мм и обработанным воском замкам.', status=<AlternativeStatus.FINAL: 3>)

Склонируйте репозиторий Yandex Cloud API, вставив код в ячейку ноутбука:
```
git clone https://github.com/yandex-cloud/cloudapi
```
Установите пакет grpcio-tools с помощью менеджера пакетов pip:
```
pip install grpcio-tools
```
Перейдите в папку со склонированным репозиторием Yandex Cloud API:
```
cd <путь_к_папке_cloudapi>
```
Создайте папку output:
```
mkdir output
```

Сгенерируйте код интерфейса клиента:

python -m grpc_tools.protoc -I . -I third_party/googleapis \
  --python_out=output \
  --grpc_python_out=output \
    google/api/http.proto \
    google/api/annotations.proto \
    yandex/cloud/api/operation.proto \
    google/rpc/status.proto \
    yandex/cloud/operation/operation.proto \
    yandex/cloud/validation.proto \
    yandex/cloud/ai/foundation_models/v1/text_generation/text_generation_service.proto \
    yandex/cloud/ai/foundation_models/v1/text_common.proto

В папке output создайте файл test.py с кодом запроса к модели:

# coding=utf8
import argparse
import grpc

import yandex.cloud.ai.foundation_models.v1.text_common_pb2 as pb
import yandex.cloud.ai.foundation_models.v1.text_generation.text_generation_service_pb2_grpc as service_pb_grpc
import yandex.cloud.ai.foundation_models.v1.text_generation.text_generation_service_pb2 as service_pb

def run(iam_token, folder_id, user_text):
    cred = grpc.ssl_channel_credentials()
    channel = grpc.secure_channel('llm.api.cloud.yandex.net:443', cred)
    stub = service_pb_grpc.TextGenerationServiceStub(channel)

    request = service_pb.CompletionRequest(
        model_uri=f"gpt://{folder_id}/yandexgpt",
        completion_options=pb.CompletionOptions(
            max_tokens={"value": 2000}, 
            temperature={"value": 0.5}
        ),
    )
    message_system = request.messages.add()
    message_system.role = "system"
    message_system.text = "Исправь ошибки в тексте."

    message_user = request.messages.add()
    message_user.role = "user"
    message_user.text = user_text

    it = stub.Completion(request, metadata=(
        ('authorization', f'Bearer {iam_token}'),
    ))
    for response in it:
        for alternative in response.alternatives:
            print (alternative.message.text)

if __name__ == '__main__':
    parser = argparse.ArgumentParser()
    parser.add_argument("--iam_token", required=True, help="IAM token")
    parser.add_argument("--folder_id", required=True, help="Folder id")
    parser.add_argument("--user_text", required=True, help="User text")
    args = parser.parse_args()
    run(args.iam_token, args.folder_id, args.user_text)

Запустите файл test.py, подставив значение IAM-токена и идентификатор каталога:

export IAM_TOKEN=<IAM-токен>
export FOLDER_ID=<идентификатор_каталога>
export TEXT='Ашипки саме сибя ни исрпвят'
python output/test.py \
  --iam_token ${IAM_TOKEN} \
  --folder_id ${FOLDER_ID} \
  --user_text ${TEXT}

Результат:

Ошибки сами себя не исправят.

Потоковый запрос через gRPC API

SDK

Python

При использовании метода run_stream сервер будет присылать не только финальный результат генерации текста, но и промежуточные результаты. Каждый промежуточный ответ содержит весь результат генерации, доступный на текущий момент. До получения финального ответа результаты генерации могут меняться с приходом новых сообщений.

Работа метода run_stream максимально наглядна при создании и обработке больших текстов.

Создайте файл generate-text.py и добавьте в него следующий код:
```
#!/usr/bin/env python3

from __future__ import annotations
from yandex_cloud_ml_sdk import YCloudML

messages = [
    {"role": "system", "text": "Найди ошибки в тексте и исправь их"},
    {"role": "user", "text": "Ашипки саме сибя ни исрпвят."},
]


def main():
    sdk = YCloudML(
        folder_id="<идентификатор_каталога>",
        auth="<API-ключ>",
    )

    model = sdk.models.completions("yandexgpt")

    for result in model.configure(temperature=0.5).run_stream(messages):
        for alternative in result:
            print(alternative)


if __name__ == "__main__":
    main()
```
Где:
- messages — массив сообщений, которые задают контекст для модели:
  - role — роль отправителя сообщения:
    - user — предназначена для отправки пользовательских сообщений к модели.
    - system — позволяет задать контекст запроса и определить поведение модели.
    - assistant — используется для ответов, которые генерирует модель. При работе в режиме чата ответы модели, помеченные ролью assistant, включаются в состав сообщения для сохранения контекста беседы. Не передавайте сообщения пользователя с этой ролью.
  - text — текстовое содержимое сообщения.
- <идентификатор_каталога> — идентификатор каталога, в котором создан сервисный аккаунт.
- <API-ключ> — API-ключ сервисного аккаунта, полученный ранее и необходимый для аутентификации в API.
  
  В примерах используется аутентификация с помощью API-ключа. Yandex Cloud ML SDK также поддерживает аутентификацию с помощью IAM-токена и OAuth-токена. Подробнее см. в разделе Аутентификация в Yandex Cloud ML SDK.
Подробнее о том, как обращаться к определенной версии модели, см. в разделе Обращение к моделям.

Выполните созданный файл:

python3 generate-text.py

Результат выполнения:

Alternative(role='assistant', text='О', status=<AlternativeStatus.PARTIAL: 1>)
Alternative(role='assistant', text='Ошибки сами себя не исправят.', status=<AlternativeStatus.FINAL: 3>)

При включенном параметре stream сервер будет присылать не только финальный результат генерации текста, но и промежуточные результаты. Каждый промежуточный ответ содержит весь результат генерации, доступный на текущий момент. До получения финального ответа результаты генерации могут меняться с приходом новых сообщений.

Работа параметра stream максимально наглядна при создании и обработке больших текстов.

Важно

Параметр stream недоступен для асинхронного режима работы модели.

Сгенерируйте код интерфейса клиента gRPC, как описано в инструкции. На шаге 6 создайте файл test.py, содержащий код обращения к модели:

# coding=utf8
import argparse
import grpc

import yandex.cloud.ai.foundation_models.v1.text_common_pb2 as pb
import yandex.cloud.ai.foundation_models.v1.text_generation.text_generation_service_pb2_grpc as service_pb_grpc
import yandex.cloud.ai.foundation_models.v1.text_generation.text_generation_service_pb2 as service_pb

def run(iam_token, folder_id, user_text):
    cred = grpc.ssl_channel_credentials()
    channel = grpc.secure_channel('llm.api.cloud.yandex.net:443', cred)
    stub = service_pb_grpc.TextGenerationServiceStub(channel)

    request = service_pb.CompletionRequest(
            model_uri=f"gpt://{folder_id}/yandexgpt",
            completion_options=pb.CompletionOptions(
                max_tokens={"value": 2000},
                temperature={"value": 0.5},
                stream=True
            ),
        )
        message_system = request.messages.add()
        message_system.role = "system"
        message_system.text = "Исправь ошибки в тексте."
    
        message_user = request.messages.add()
        message_user.role = "user"
        message_user.text = user_text
    
        it = stub.Completion(request, metadata=(
            ('authorization', f'Bearer {iam_token}'),
        ))             
        
        for response in it:
            print(response)

if __name__ == '__main__':
    parser = argparse.ArgumentParser()
    parser.add_argument("--iam_token", required=True, help="IAM token")
    parser.add_argument("--folder_id", required=True, help="Folder id")
    parser.add_argument("--user_text", required=True, help="User text")
    args = parser.parse_args()
    run(args.iam_token, args.folder_id, args.user_text)

Результат:

alternatives {
  message {
    role: "assistant"
    text: "О"
  }
  status: ALTERNATIVE_STATUS_PARTIAL
}
usage {
  input_text_tokens: 29
  completion_tokens: 1
  total_tokens: 30
}
model_version: "07.03.2024"

alternatives {
  message {
    role: "assistant"
    text: "Ошибки сами себя не исправят."
  }
  status: ALTERNATIVE_STATUS_FINAL
}
usage {
  input_text_tokens: 29
  completion_tokens: 9
  total_tokens: 38
}
model_version: "07.03.2024"

См. также

Обзор возможностей генерации текста
Примеры работы с ML SDK на GitHub

Отправить запрос в промт-режиме

Перед началом работыПеред началом работы

Запрос к модели через REST APIЗапрос к модели через REST API

Запрос к модели через gRPC APIЗапрос к модели через gRPC API

Потоковый запрос через gRPC APIПотоковый запрос через gRPC API

См. такжеСм. также

Была ли статья полезна?

Перед началом работы

Запрос к модели через REST API

Запрос к модели через gRPC API

Потоковый запрос через gRPC API

См. также