ym88659208ym87991671
Генерация структурированных данных | Документация для разработчиков

Генерация структурированных данных

Обновлено 20 июля 2026

Модели GigaChat могут генерировать структурированные данные в соответствии с переданной в запросе JSON-схемой или регулярным выражением. Такая функциональность полезна, например, для извлечения сущностей из текста или парсинга документов.

Как и для генерации текста, для получения структурированных данных используются запросы POST /v1/chat/completions и POST /v2/chat/completions.

Формат и схема данных задаются в объекте response_format. Возможные значения поля response_format.type:

  • text — принудительная генерация текста. В этом случае объект response_format не может содержать другие поля;
  • json_schema — генерация JSON-объекта, обернутого в строку. Схема объекта передается в поле response_format.schema.

Примеры запросов:

from gigachat import GigaChat
from gigachat.models import Chat, Messages, MessagesRole

from gigachat import GigaChat

client = GigaChat(
    base_url="https://api.giga.chat/v1",
    credentials="<ключ_авторизации>",
    scope="GIGACHAT_API_CORP",
    verify_ssl_certs=False,
)

PROMPT = "27 октября 2023 года у меня родился сын"

chat = Chat(
    model="GigaChat-2-Max",
    messages=[Messages(role=MessagesRole.USER, content=PROMPT)],
    response_format={
		"type": "json_schema",
		"schema": {
			"type": "object",
			"properties": {
				"date": {
					"type": "string",
					"description": "Дата в формате dd.mm"
				},
				"event": {
					"type": "string",
					"description": "Наименование события"
				}
			},
			"additionalProperties": True,
			"required": [
				"date"
			]
		},
		"strict": True
	},
)

resp = client.chat(chat)

print(resp)

Пример ответа модели в виде обернутого в строку JSON-объекта:

{
  "choices": [
    {
      "message": {
        "content": "{\n    \"date\": \"27 октября 2023\",\n    \"event\": \"рождение сына\"\n}",
        "role": "assistant"
      },
      "index": 0,
      "finish_reason": "stop"
    }
  ],
  "created": 1781694805,
  "model": "GigaChat-2-Max:2.0.30.01",
  "object": "chat.completions",
  "usage": {
    "prompt_tokens": 29,
    "completion_tokens": 32,
    "total_tokens": 61,
    "precached_prompt_tokens": 3
  }
}

Описание схемы данных

Схема данных, которой должен соответствовать ответ модели, передается в поле response_format.schema. При этом, если в схеме отсутствует описание обязательных полей в массиве required, модель сгенерирует произвольный JSON-объект.

Чтобы ответ строго соответствовал схеме, передайте список обязательных полей в массиве required и задайте параметр "strict": true. Тогда ответ будет содержать все поля, в том числе необязательные. Если передать список обязательных полей без параметра "strict": true, ответ модели может содержать поля, неописанные в схеме.

Вы также можете задать схему данных с помощью модели Pydantic.

{
	"response_format": {
		"type": "json_schema",
		"schema": {
			"type": "object",
			"properties": {
				"date": {
					"type": "string",
					"description": "Дата в формате dd.mm"
				},
				"event": {
					"type": "string",
					"description": "Наименование события"
				}
			},
			"additionalProperties": true,
			"required": [
				"date"
			]
		},
		"strict": true
	}
}

Структурированные данные в v2/chat/completions

В отличие от POST /v1/chat/completions, в запросе POST /v2/chat/completions параметры структурированного вывода и описание схемы данных передаются в объекте model_options.response_format. В остальном оба способа работают одинаково:

from gigachat import GigaChat
from gigachat.models import ChatCompletionRequest, ChatMessage, ChatModelOptions, ChatResponseFormat

SCHEMA = {
    "type": "object",
    "properties": {
        "date": {
            "type": "string",
            "description": "Дата в формате dd.mm"
        },
        "event": {
            "type": "string",
            "description": "Наименование события"
        }
    },
    "additionalProperties": True,
    "required": ["date"]
}

request = ChatCompletionRequest(
    model="GigaChat-2-Max",
    messages=[ChatMessage(role="user", content=[{"text": "27 октября 2023 года у меня родился сын"}])],
    model_options=ChatModelOptions(
        response_format=ChatResponseFormat(
            type="json_schema",
            schema=SCHEMA,
            strict=True,
        )
    ),
)

client = GigaChat(
    base_url="https://api.giga.chat/v1",
    credentials="<ключ_авторизации>",
    scope="GIGACHAT_API_CORP",
    verify_ssl_certs=False,
)

response = client.chat.create(request)
print(response)

Структура ответа также отличается от POST /v1/chat/completions:

{
  "model": "GigaChat-2-Max:2.0.30.01",
  "created_at": 1781694924,
  "messages": [
    {
      "role": "assistant",
      "content": [
        {
          "text": " {\n    \"date\": \"27 октября 2023\",\n    \"event\": \"рождение сына\"\n}"
        }
      ]
    }
  ],
  "finish_reason": "stop",
  "usage": {
    "input_tokens": 29,
    "input_tokens_details": { "prompt_tokens": 29, "cached_tokens": 3 },
    "output_tokens": 31,
    "total_tokens": 60
  }
}

Потоковая передача данных

Структурированные данные можно получать в потоке SSE-событий так же, как и обычный текст. Для запуска потоковой передачи данных используйте метод stream().

Запрос POST /v1/chat/completions:

from gigachat import GigaChat
from gigachat.models import Chat, Messages, MessagesRole

from gigachat import GigaChat

PROMPT = "27 октября 2023 года у меня родился сын"

chat = Chat(
    model="GigaChat-2-Max",
    messages=[Messages(role=MessagesRole.USER, content=PROMPT)],
    response_format={
		"type": "json_schema",
		"schema": {
			"type": "object",
			"properties": {
				"date": {
					"type": "string",
					"description": "Дата в формате dd.mm"
				},
				"event": {
					"type": "string",
					"description": "Наименование события"
				}
			},
			"additionalProperties": True,
			"required": [
				"date"
			]
		},
		"strict": True
	},
)

client = GigaChat(
    base_url="https://api.giga.chat/v1",
    credentials="<ключ_авторизации>",
    scope="GIGACHAT_API_CORP",
    verify_ssl_certs=False,
)

# Извлечение и построчное отображение содержимого событий
for chunk in client.stream(chat):
    print(chunk.choices[0].delta.content, end="", flush=True)

Запрос POST /v2/chat/completions:

from gigachat import GigaChat
from gigachat.models import ChatCompletionRequest, ChatMessage, ChatModelOptions, ChatResponseFormat

SCHEMA = {
    "type": "object",
    "properties": {
        "date": {
            "type": "string",
            "description": "Дата в формате dd.mm"
        },
        "event": {
            "type": "string",
            "description": "Наименование события"
        }
    },
    "additionalProperties": True,
    "required": ["date"]
}

request = ChatCompletionRequest(
    model="GigaChat-2-Max",
    messages=[ChatMessage(role="user", content=[{"text": "27 октября 2023 года у меня родился сын"}])],
    model_options=ChatModelOptions(
        response_format=ChatResponseFormat(
            type="json_schema",
            schema=SCHEMA,
            strict=True,
        )
    ),
)

client = GigaChat(
    base_url="https://api.giga.chat/v1",
    credentials="<ключ_авторизации>",
    scope="GIGACHAT_API_CORP",
    verify_ssl_certs=False,
)

# Извлечение и построчное отображение содержимого событий
for chunk in client.chat.stream(request):
    for msg in chunk.messages or []:
        for part in msg.content or []:
            if text := part.text:
                print(text, end="", flush=True)

При работе с потоковой передачей учитывайте, что формат событий в ответе на запросы POST /v1/chat/completions и POST /v2/chat/completions отличается:

data: {"choices":[{"delta":{"content":"{\n    \"date\":","role":"assistant"},"index":0}],"created":1781695039,"model":"GigaChat-2-Max:2.0.30.01","object":"chat.completions"}

data: {"choices":[{"delta":{"content":" \"2023-10-27\",\n    \"event\":","role":"assistant"},"index":0}],"created":1781695039,"model":"GigaChat-2-Max:2.0.30.01","object":"chat.completions"}

data: {"choices":[{"delta":{"content":" \"рождение сына\"\n}","role":"assistant"},"index":0}],"created":1781695039,"model":"GigaChat-2-Max:2.0.30.01","object":"chat.completions"}

data: {"choices":[{"delta":{"content":""},"index":0,"finish_reason":"stop"}],"created":1781695039,"model":"GigaChat-2-Max:2.0.30.01","object":"chat.completions","usage":{"prompt_tokens":29,"completion_tokens":34,"total_tokens":63,"precached_prompt_tokens":3}}

data: [DONE]

Разбор ответа с помощью chat_parse()

Используйте метод chat_parse(), чтобы автоматически разобрать JSON и провалидировать его с помощью Pydantic-модели. Метод возвращает как разобранный JSON, так и исходные данные в экземпляре ChatCompletion.

from gigachat import GigaChat
from gigachat.models import ChatCompletionRequest, ChatMessage, ChatModelOptions, ChatResponseFormat
from pydantic import BaseModel, Field

class Event(BaseModel):
    date: str = Field(description="Дата в формате dd.mm")
    event: str | None = Field(default=None, description="Наименование события")

PROMPT = "27 октября 2023 года у меня родился сын"

with GigaChat(
    base_url="https://api.giga.chat/v1",
    credentials="<ключ_авторизации>",
    scope="GIGACHAT_API_CORP",
    verify_ssl_certs=False,
) as client:
    completion, parsed_response = client.chat_parse(
        PROMPT,
        response_format=Event,
        strict=True,
    )


print("=== client.chat_parse() ===")
print("Дата:", parsed_response.date)
print("Событие:", parsed_response.event)
print(f"Кол-во токенов: {completion.usage.total_tokens}")

Заметили ошибку?

Выделите текст и нажмите Ctrl + Enter, чтобы сообщить нам о ней