Using prompt-based classifiers based on YandexGPT

Yandex Cloud AI Studio provides YandexGPT prompt-based classifiers of these two types: zero-shot and few-shot. To send a request to a prompt-based classifier, use the fewShotClassify text classification API method or Yandex Cloud ML SDK.

To use the example, you will need a service account with the ai.languageModels.user role and an API key with the yc.ai.foundationModels.execute scope. The API key you can create in AI Studio has these permissions. Refer to the Getting started section for an example of how to configure your runtime environment.

Send a request to the classifier

  • Example 1: Request to the zero-shot classifier.
  • Example 2: Request to the few-shot classifier.
import os
        import time
        import requests
        
        YANDEX_API_KEY = os.environ["YANDEX_API_KEY"]
        YANDEX_FOLDER_ID = os.environ["YANDEX_FOLDER_ID"]
        
        headers = {
            "Authorization": f"Api-Key {YANDEX_API_KEY}",
            "Content-Type": "application/json",
        }
        
        request_text = "translate into Russian \"what's the weather like in london?\""
        
        # Example 1: Zero-shot classifier
        zero_shot_body = {
            "modelUri": f"cls://{YANDEX_FOLDER_ID}/yandexgpt/latest",
            "text": request_text,
            "taskDescription": "determine the intent type",
            "labels": ["translation", "alarm", "weather"],
        }
        
        response = requests.post(
            "https://llm.api.cloud.yandex.net/foundationModels/v1/fewShotTextClassification",
            headers=headers,
            json=zero_shot_body,
        )
        print("Zero-shot:", response.json())
        
        time.sleep(1)
        
        # Example 2: Few-shot classifier
        few_shot_body = {
            "modelUri": f"cls://{YANDEX_FOLDER_ID}/yandexgpt/latest",
            "text": request_text,
            "taskDescription": "determine the intent type",
            "labels": ["translation", "alarm", "weather"],
            "samples": [
                {"text": "set an alarm", "label": "alarm"},
                {"text": "weather for tomorrow", "label": "weather"},
                {"text": "translate the phrase \"set an alarm\"", "label": "translation"},
            ],
        }
        
        response = requests.post(
            "https://llm.api.cloud.yandex.net/foundationModels/v1/fewShotTextClassification",
            headers=headers,
            json=few_shot_body,
        )
        print("Few-shot:", response.json())

Where:

  • YANDEX_API_KEY: API key for access to AI Studio.
  • YANDEX_FOLDER_ID: Service account folder ID.
  • modelUri: ID of the model that will be used to classify the message.
  • text: Message text.
  • taskDescription: Text description of the task for the classifier.
  • labels: Array of classes.
  • samples: Array with examples of requests for the classes specified in the labels field (few-shot only).

Zero-shot response example:

{
          "predictions": [
            {
              "label": "translation",
              "confidence": 0.9999989947078635
            },
            {
              "label": "alarm",
              "confidence": 2.646570978329449e-09
            },
            {
              "label": "weather",
              "confidence": 2.646570978329449e-09
            }
          ],
          "modelVersion": "09.02.2025"
        }

Few-shot response example:

{
          "predictions": [
            {
              "label": "translation",
              "confidence": 0.9357050657272339
            },
            {
              "label": "alarm",
              "confidence": 0.00061939493753016
            },
            {
              "label": "weather",
              "confidence": 0.06367553025484085
            }
          ],
          "modelVersion": "09.02.2025"
        }
        
const YANDEX_API_KEY = process.env.YANDEX_API_KEY;
        const YANDEX_FOLDER_ID = process.env.YANDEX_FOLDER_ID;
        
        const headers = {
          Authorization: `Api-Key ${YANDEX_API_KEY}`,
          "Content-Type": "application/json",
        };
        
        const requestText = 'translate into Russian \"what\'s the weather like in london?\"';
        
        // Example 1: Zero-shot classifier
        const zeroShotBody = {
          modelUri: `cls://${YANDEX_FOLDER_ID}/yandexgpt/latest`,
          text: requestText,
          taskDescription: "determine the intent type",
          labels: ["translation", "alarm", "weather"],
        };
        
        let response = await fetch(
          "https://llm.api.cloud.yandex.net/foundationModels/v1/fewShotTextClassification",
          { method: "POST", headers, body: JSON.stringify(zeroShotBody) }
        );
        console.log("Zero-shot:", await response.json());
        
        await new Promise((r) => setTimeout(r, 1000));
        
        // Example 2: Few-shot classifier
        const fewShotBody = {
          modelUri: `cls://${YANDEX_FOLDER_ID}/yandexgpt/latest`,
          text: requestText,
          taskDescription: "determine the intent type",
          labels: ["translation", "alarm", "weather"],
          samples: [
            { text: "set an alarm", label: "alarm" },
            { text: "weather for tomorrow", label: "weather" },
            { text: 'translate the phrase "set an alarm"', label: "translation" },
          ],
        };
        
        response = await fetch(
          "https://llm.api.cloud.yandex.net/foundationModels/v1/fewShotTextClassification",
          { method: "POST", headers, body: JSON.stringify(fewShotBody) }
        );
        console.log("Few-shot:", await response.json());

Where:

  • YANDEX_API_KEY: API key for access to AI Studio.
  • YANDEX_FOLDER_ID: Service account folder ID.
  • modelUri: ID of the model that will be used to classify the message.
  • text: Message text.
  • taskDescription: Text description of the task for the classifier.
  • labels: Array of classes.
  • samples: Array with examples of prompts for the classes specified in the labels field (few-shot only).

Zero-shot response example:

{
          "predictions": [
            {
              "label": "translation",
              "confidence": 0.9999989947078635
            },
            {
              "label": "alarm",
              "confidence": 2.646570978329449e-09
            },
            {
              "label": "weather",
              "confidence": 2.646570978329449e-09
            }
          ],
          "modelVersion": "09.02.2025"
        }

Few-shot response example:

{
          "predictions": [
            {
              "label": "translation",
              "confidence": 0.9357050657272339
            },
            {
              "label": "alarm",
              "confidence": 0.00061939493753016
            },
            {
              "label": "weather",
              "confidence": 0.06367553025484085
            }
          ],
          "modelVersion": "09.02.2025"
        }
        
package main
        
        import (
            "bytes"
            "encoding/json"
            "fmt"
            "io"
            "log"
            "net/http"
            "os"
            "time"
        )
        
        func classify(apiKey string, body map[string]any) {
            data, _ := json.Marshal(body)
            req, _ := http.NewRequest("POST",
                "https://llm.api.cloud.yandex.net/foundationModels/v1/fewShotTextClassification",
                bytes.NewReader(data))
            req.Header.Set("Authorization", "Api-Key "+apiKey)
            req.Header.Set("Content-Type", "application/json")
        
            resp, err := http.DefaultClient.Do(req)
            if err != nil {
                log.Fatalf("Request error: %v", err)
            }
            defer resp.Body.Close()
        
            result, _ := io.ReadAll(resp.Body)
            fmt.Println(string(result))
        }
        
        func main() {
            apiKey := os.Getenv("YANDEX_API_KEY")
            folderID := os.Getenv("YANDEX_FOLDER_ID")
            modelUri := fmt.Sprintf("cls://%s/yandexgpt/latest", folderID)
            requestText := "translate into Russian \"what's the weather like in london?\""
        
            // Example 1: Zero-shot classifier
            classify(apiKey, map[string]any{
                "modelUri":        modelUri,
                "text":            requestText,
                "taskDescription": "determine the intent type",
                labels:          []string{"translation", "alarm", "weather"},
            })
        
            time.Sleep(time.Second)
        
            // Example 2: Few-shot classifier
            classify(apiKey, map[string]any{
                "modelUri":        modelUri,
                "text":            requestText,
                "taskDescription": "determine the intent type",
                labels:          []string{"translation", "alarm", "weather"},
                "samples": []map[string]string{
                    {"text": "set an alarm", "label": "alarm"},
                    {"text": "weather for tomorrow", "label": "weather"},
                    {"text": "translate the phrase \"set an alarm\"", "label": "translation"},
                },
            })
        }

Where:

  • YANDEX_API_KEY: API key for access to AI Studio.
  • YANDEX_FOLDER_ID: Service account folder ID.
  • modelUri: ID of the model that will be used to classify the message.
  • text: Message text.
  • taskDescription: Text description of the task for the classifier.
  • labels: Array of classes.
  • samples: Array with examples of requests for the classes specified in the labels field (few-shot only).

Zero-shot response example:

{
          "predictions": [
            {
              "label": "translation",
              "confidence": 0.9999989947078635
            },
            {
              "label": "alarm",
              "confidence": 2.646570978329449e-09
            },
            {
              "label": "weather",
              "confidence": 2.646570978329449e-09
            }
          ],
          "modelVersion": "09.02.2025"
        }

Few-shot response example:

{
          "predictions": [
            {
              "label": "translation",
              "confidence": 0.9357050657272339
            },
            {
              "label": "alarm",
              "confidence": 0.00061939493753016
            },
            {
              "label": "weather",
              "confidence": 0.06367553025484085
            }
          ],
          "modelVersion": "09.02.2025"
        }

The example below is for MacOS and Linux. To implement it in Windows, see how to use Bash in Microsoft Windows.

# Request to a zero-shot classifier
        curl -s https://llm.api.cloud.yandex.net/foundationModels/v1/fewShotTextClassification \
          --request POST \
          --header "Content-Type: application/json" \
          --header "Authorization: Api-Key <API_key>" \
          --data '{
            "modelUri": "cls://<folder_ID>/yandexgpt/latest",
            "text": "5:0",
            "taskDescription": "Categorize an article by its title",
            "labels": ["culture", "technologies", "sports"]
          }' | jq .
        
        # Request to a few-shot classifier
        curl -s https://llm.api.cloud.yandex.net/foundationModels/v1/fewShotTextClassification \
          --request POST \
          --header "Content-Type: application/json" \
          --header "Authorization: Api-Key <API_key>" \
          --data '{
            "modelUri": "cls://<folder_ID>/yandexgpt/latest",
            "text": "translate into Russian \"what's the weather like in london?\"",
            "taskDescription": "determine the intent type",
            "labels": ["translation", "alarm", "weather"],
            "samples": [
              {"text": "set an alarm", "label": "alarm"},
              {"text": "weather for tomorrow", "label": "weather"},
              {"text": "translate the phrase \"set an alarm\"", "label": "translation"}
            ]
          }' | jq .

Where:

  • <API_key>: API key for access to AI Studio.

  • <folder_ID>: Service account folder ID.

  • modelUri: ID of the model that will be used to classify the message.

  • text: Message text.

  • taskDescription: Text description of the task for the classifier.

  • labels: Array of classes.

  • samples: Array with examples of requests for the classes specified in the labels field (few-shot only). Examples of prompts are provided as objects, each containing an example of a text query and the class to which such query should belong.

    Give meaningful names to classes in labels: this is essential for correct classification results. For example, use chemistry and physics rather than chm and phs for class names.

Zero-shot response example:

{
          "predictions": [
            {
              "label": "culture",
              "confidence": 2.2111835562554916e-7
            },
            {
              "label": "technologies",
              "confidence": 0.0003487042267806828
            },
            {
              "label": "sports",
              "confidence": 0.9996510744094849
            }
          ],
          "modelVersion": "07.03.2024"
        }

Few-shot response example:

{
          "predictions": [
            {
              "label": "translation",
              "confidence": 0.9357050657272339
            },
            {
              "label": "alarm",
              "confidence": 0.00061939493753016
            },
            {
              "label": "weather",
              "confidence": 0.06367553025484085
            }
          ],
          "modelVersion": "07.03.2024"
        }

Note

The https://llm.api.cloud.yandex.net/foundationModels/v1/fewShotTextClassification endpoint only works with prompt-based classifiers. For fine-tuned classifiers, use https://llm.api.cloud.yandex.net:443/foundationModels/v1/textClassification.

#!/usr/bin/env python3
        # pylint: disable=duplicate-code
        
        from __future__ import annotations
        import os
        from yandex_ai_studio_sdk import AIStudio
        
        request_text = 'translate into Russian \"what\'s the weather like in london?\"'
        
        
        def main():
            sdk = AIStudio(
                folder_id=os.environ["YANDEX_FOLDER_ID"],
                auth=os.environ["YANDEX_API_KEY"],
            )
        
            # Sample 1: Zero-shot classification
            model = sdk.models.text_classifiers("yandexgpt").configure(
                task_description="determine the intent type",
                labels=["translation", "alarm", "weather"],
            )
        
            result = model.run(request_text)
        
            print("Zero-shot classification:")
        
            for prediction in result:
                print(prediction)
        
            # Sample 2: Few-shot classification
            model = model.configure(
                task_description="determine the intent type",
                labels=["translation", "alarm", "weather"],
                samples=[
                    {"text": "set an alarm", "label": "alarm"},
                    {"text": "weather for tomorrow", "label": "weather"},
                    {"text": 'translate the phrase "set an alarm"', "label": "translation"},
                ],
            )
        
            result = model.run(request_text)
        
            print("Few-shot classification:")
        
            for prediction in result:
                print(prediction)
        
        
        if __name__ == "__main__":
            main()

Where:

  • request_text: Message text.

    As input data for a request, Yandex Cloud ML SDK can accept a string, a dictionary, an object of the TextMessage class, or an array containing any combination of these data types. For more information, see Yandex Cloud ML SDK usage.

For more information about accessing classifier models, see Accessing models.

Response example:

TextClassificationLabel(label='translation', confidence=0.9999947046656092)
        TextClassificationLabel(label='alarm', confidence=6.01089130732152e-09)
        TextClassificationLabel(label='weather', confidence=4.289328794822987e-06)
        Few-shot classification:
        TextClassificationLabel(label='translation', confidence=0.9999989886405171)
        TextClassificationLabel(label='alarm', confidence=4.4148929001561725e-09)
        TextClassificationLabel(label='weather', confidence=6.945601458737463e-09)

See also

Previous
Image generation
Next
Classification with a fine-tuned model