Обращение к встроенным функциям

Обновлено 4 августа 2025

Встроенные функции — это функции, которые исполняются внутри сервиса GigaChat. Так, если после авторизации на giga.chat , вы попросите модель нарисовать картинку, она обратится к встроенной функции text2image. Модель покажет итоговое изображение, созданное этой функцией.

Моделям доступны функции:

• text2image

  Генерация изображения в формате JPEG.

  Для работы с функцией передайте запрос с включенным автоматическим режимом "function_call": "auto". При этом в запросе не должно быть массива functions или он должен содержать название функции.

• get_file_content

  Использование текстовых документов для генерации ответа.

  Функцию можно использовать, если передать в запросе массив functions и/или "function_call": "auto", а также идентификаторы файлов в массиве attachments. Посмотреть доступные в хранилище файлы можно с помощью метода GET /files. Подробнее — в разделе Обработка файлов.

• text2model3d

  Генерация модели в формате FBX.

  Для обращения к функции генерации 3D-модели запрос должен содержать ее название в массиве functions, а также поле "function_call": "auto".

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

Создание изображения

Чтобы модель сгенерировала изображение по описанию, переданному в промпте, запустите работу с функциями в авторежиме ("function_call": "auto"):

• cURL
• Python
• JS/TS

curl -L -X POST 'https://gigachat.devices.sberbank.ru/api/v1/chat/completions' \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-H 'Authorization: Bearer <токен_доступа>' \
--data-raw '{
  "model": "GigaChat",
  "messages": [
    {
      "role": "system",
      "content": "Ты — Василий Кандинский"      
    },
    {
      "role": "user",
      "content": "Нарисуй розового кота"
    }
  ],
  "function_call": "auto"
}'

Обращение к функции с помощью SDK:

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

giga = GigaChat(credentials="<ключ_авторизации>", verify_ssl_certs=False)

payload = Chat(
    messages=[Messages(role=MessagesRole.USER, content="Нарисуй космонавта верхом на лошади")],
    function_call="auto",
)

response = giga.chat(payload)

print (response)

Обращение к функции с помощью партнерского пакета langchain-gigachat:

from langchain_gigachat.chat_models import GigaChat
from langchain_core.prompts import ChatPromptTemplate, MessagesPlaceholder

llm = GigaChat(
    credentials="<ключ_авторизации>",
    verify_ssl_certs=False,
)

# Метод `bind_tools(tools=[], tool_choice="auto")` сообщает модели, что нужно использовать встроенные функции.
llm = llm.bind_tools(tools=[], tool_choice="auto")

# Промпт для создания изображения
prompt = ChatPromptTemplate.from_messages(
    [
        (
            "system",
            """Ты — Василий Кандинский.""",
        ),
        ("user", """{topic}"""),
    ]
)

# Цепочка для создания изображения
generate_image_chain = prompt | llm

response = generate_image_chain.invoke({"topic": "Нарисуй розового кота"})

print(response)

Обращение к функции с помощью SDK:

import { GigaChat } from 'gigachat';

const giga = new GigaChat({
    credentials: '<ключ_авторизации>',
});

const resp = await giga.chat({
  messages: [
    {
        "role": "system",
        "content": "Ты — Василий Кандинский"      
    },
    {
      role: "user",
      content: "Нарисуй розового кота",
    },
  ],
  function_call: 'auto',
});

console.log(resp.choices[0]?.message.content);

Обращение к функции с помощью партнерского пакета langchain-gigachat:

import { GigaChat } from "langchain-gigachat"
import { HumanMessage, SystemMessage } from "@langchain/core/messages";

const llm = new GigaChat({
  credentials: '<ключ_авторизации>',
});

const messages = [
  new SystemMessage("Ты — Василий Кандинский."),
  new HumanMessage("Нарисуй розового кота."),
];

const llmWithFunctions = llm.bindTools([], {tool_choice: 'auto'});

const response = await llmWithFunctions.invoke(messages);

console.log(response.content)

Ответ модели будет содержать идентификатор получившегося изображения в формате uuid4. Идентификатор передается в поле message.content, в теге <img>, в атрибуте src:

{
    "choices": [
        {
            "message": {
                "content": "Запускаю генерацию изображения. Ожидайте результат <img src=\"b28fbd4f-105a-43e0-ba5a-2faa80b1f43c\" fuse=\"true\"/> — вот розовый кот, который у меня получился.",
                "role": "assistant",
                "functions_state_id": "77d3fb14-457a-46ba-937e-8d856156d003"
            },
            "index": 0,
            "finish_reason": "stop"
        }
    ],
    "created": 1716367703,
    "model": "GigaChat:3.1.25.3",
    "object": "chat.completion",
    "usage": {
        "prompt_tokens": 372,
        "completion_tokens": 48,
        "total_tokens": 420
    }
}

Для скачивания файла из хранилища используйте метод GET /files/{file_id}/content:

curl -L -X GET 'https://gigachat.devices.sberbank.ru/api/v1/files/<идентификатор_файла>/content' -o "<имя_файла>.jpeg" \
-H 'Accept: application/jpeg' \
-H 'Authorization: Bearer <токен_доступа>'

Создание 3D-модели

Для создания 3D-модели запустите работу с функциями в автоматическом режиме и передайте название функции в массиве functions:

• cURL
• Python
• JS/TS

curl -L -X POST 'https://gigachat.devices.sberbank.ru/api/v1/chat/completions' \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-H 'Authorization: Bearer <токен_доступа>' \
--data-raw '{
  "model": "GigaChat",
  "messages": [
    {
      "role": "user",
      "content": "Сгенерируй 3D-модель шара"
    }
  ],
  "function_call": "auto",
  "functions": [
        {
            "name": "text2model3d"			
        }
    ]
}'

Обращение к функции с помощью SDK:

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

giga = GigaChat(
    credentials="<ключ_авторизации>",
    verify_ssl_certs=False,
    # Повышеине времени ожидания, так как создание модели — длительный процесс
    timeout=200
    )

payload = Chat(
    messages=[Messages(role=MessagesRole.USER, content="Сгенерируй 3D-модель шара")],
    function_call="auto",
    functions=[
        Function(name="text2model3d")
    ]
)

response = giga.chat(payload)
print (response)

Обращение к функции с помощью партнерского пакета langchain-gigachat:

from langchain_gigachat.chat_models import GigaChat
from langchain_core.prompts import ChatPromptTemplate

llm = GigaChat(
    credentials="<ключ_авторизациии>",
    verify_ssl_certs=False,
    # Повышеине времени ожидания, так как создание модели — длительный процесс
    timeout=200
)

tools = [
    {
        "name": "text2model3d",
    },
]

# Метод `bind_tools(tools=[], tool_choice="auto")` сообщает модели, что нужно использовать встроенные функции.
llm = llm.bind_tools(tools=tools, tool_choice="auto")

# Промпт для создания изображения
prompt = ChatPromptTemplate.from_messages(
    [
        ("user", """{topic}"""),
    ]
)

# Цепочка для создания 3D-модели
generate_3d_model_chain = prompt | llm

response = generate_3d_model_chain.invoke({"topic": "Сгенерируй 3D-модель шара"})

print(response)

Обращение к функции с помощью SDK:

import { GigaChat } from 'gigachat';
import { Agent } from 'node:https';

const httpsAgent = new Agent({
  rejectUnauthorized: false,
});

const giga = new GigaChat({
    credentials: '<ключ_авторизации>',
    timeout: 200
});

const resp = await giga.chat({
  messages: [
    {
      role: "user",
      content: "Сгенерируй 3D-модель шара",
    },
  ],
  functions: [
    {"name": 'text2model3d',}
  ],
  function_call: 'auto'
});

console.log(resp.choices[0]?.message.content);

Ответ модели будет содержать <div>-блок с атрибутом data-model-id, в котором передается идентификатор сгенерированной 3D-модели.

{
    "choices": [
        {
            "message": {  
            "content": "<div data-model-id=\"2dc37408-f70a-4225-8e0a-8da749ceffac\" fuse=\"true\"/> получилась такая 3D модель шара.",  
            "role": "assistant",  
            "functions_state_id": "7421eccb-f732-483b-9018-755233d3f3b7"  
            },
            "index": 0,
            "finish_reason": "stop"
        }
    ],
    "created": 1716367703,
    "model": "GigaChat:3.1.25.3",
    "object": "chat.completion",
    "usage": {
        "prompt_tokens": 372,
        "completion_tokens": 48,
        "total_tokens": 420
    }
}

Для скачивания файла из хранилища используйте метод GET /files/{file_id}/content:

curl -L -X GET 'https://gigachat.devices.sberbank.ru/api/v1/files/<идентификатор_3d_модели>/content' -o "<имя_файла>.fbx" \
-H 'Accept: application/jpeg' \
-H 'Authorization: Bearer <токен_доступа>'

Обработка документов

Модели могут обращаться к встроенной функции обработки документов, если массив attachments содержит идентификаторы документов, а работа с функциями запущена в авторежиме ("function_call": "auto").

Посмотреть доступные в хранилище файлы можно с помощью метода GET /files.

Подробнее — в разделе Обработка файлов.

Пример:

curl --location 'https://gigachat.devices.sberbank.ru/api/v1/chat/completions' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <ключ_авторизации>' \
--data '{
  "model": "GigaChat-2-Max",
  "function_call": "auto",
  "messages": [
        {
            "role": "user",
            "content": "Сделай краткий пересказ документа",
            "attachments": [
              "e28a83b0-611c-4d15-930a-eb742385245b" 
            ]
        }
    ]
}'

Совместное использование встроенных и пользовательских функций

При работе с пользовательскими функциями, запрос всегда будет содержать массив functions.

Чтобы модели могли обращаться к встроенным функциям, их названия нужно обязательно передавать в массиве functions вместе с описанием пользовательских функций:

• cURL
• Python
• JS/TS

curl --location 'https://gigachat.devices.sberbank.ru/api/v1/chat/completions' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <токен_доступа>' \
--data '{
    "model": "GigaChat-2-Pro",
    "messages": [
        {
            "role": "user",
            "content": "Нарисуй горы"
        }
    ],
    "function_call": "auto",
    "functions": [
        {
            "name": "text2image"
        },
        {
            "name": "weather_forecast",
            "description": "Возвращает температуру на заданный период",
            "parameters": {
                "type": "object",
                "properties": {
                    "location": {
                        "type": "string",
                        "description": "Местоположение, например, название города"
                    },
                    "format": {
                        "type": "string",
                        "enum": [
                            "celsius",
                            "fahrenheit"
                        ],
                        "description": "Единицы измерения температуры"
                    },
                    "num_days": {
                        "type": "integer",
                        "description": "Период, для которого нужно вернуть"
                    }
                },
                "required": [
                    "location",
                    "format"
                ]
            }
        }
    ]
}'

Совместное использование функций с помощью SDK:

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

giga = GigaChat(credentials="<ключ_авторизации>", verify_ssl_certs=False)

weather_forecast_function=Function(
    name="weather_forecast",
    description="Возвращает температуру на заданный период",
    parameters=FunctionParameters(
        type="object",
         properties={
             "location": {"type": "string", "description": "Местоположение, например, название города"},
             "format": {"type": "string", "enum": ["celsius", "fahrenheit"], "description": "Единицы измерения температуры"},
             "num_days": {"type": "integer", "description": "Период, для которого нужно вернуть"}},
         required=["location","format"],
    )
)

payload = Chat(
    messages=[Messages(role=MessagesRole.USER, content="Погода в Манжероке на три дня")],
    function_call="auto",
    functions=[
        Function(name="text2image"),
        weather_forecast_function
    ]
)

response = giga.chat(payload)
print (response)

Совместное использование функций с помощью партнерского пакета langchain-gigachat:

from langchain_gigachat.chat_models import GigaChat
from langchain_core.prompts import ChatPromptTemplate

llm = GigaChat(
    credentials="<ключ_авторизации>",
    verify_ssl_certs=False
)

tools = [
    {
        "name": "text2image",
    },
    {
        "name": "weather_forecast",
        "description": "Возвращает температуру на заданный период",
        "parameters": {
            "type": "object",
            "properties": {
                "location": {
                    "type": "string",
                    "description": "Местоположение, например, название города"
                },
                "format": {
                    "type": "string",
                    "enum": [
                        "celsius",
                        "fahrenheit"
                    ],
                    "description": "Единицы измерения температуры"
                },
                "num_days": {
                    "type": "integer",
                    "description": "Период, для которого нужно вернуть"
                }
            },
            "required": [
                "location",
                "format"
            ]
        }
    }
]

llm = llm.bind_tools(tools=tools, tool_choice="auto")

prompt = ChatPromptTemplate.from_messages(
    [
        ("user", """{topic}"""),
    ]
)

combined_functions_chain = prompt | llm

response = combined_functions_chain.invoke({"topic": "Погода в Манжероке на три дня"})

print(response)

Обращение к функции с помощью SDK:

import { GigaChat } from 'gigachat';

const giga = new GigaChat({
    credentials: '<ключ_авторизации>',
});

const weatherForecast = {
    name: "weather_forecast",
    description: "Возвращает температуру на заданный период",
    parameters: {
        type: "object",
        properties: {
            location: {
                type: "string",
                description: "Местоположение, например, название города"
            },
            format: {
                type: "string",
                enum: [
                    "celsius",
                    "fahrenheit"
                ],
                description: "Единицы измерения температуры"
            },
            num_days: {
                type: "integer",
                description: "Период, для которого нужно вернуть"
            }
        },
        required: [
            "location",
            "num_days"
        ]
    },
    return_parameters: {
        type: "object",
        properties: {
            location: {
                type: "string",
                description: "Местоположение, например, название города"
            },
            temperature: {
                type: "integer",
                description: "Температура для заданного местоположения"
            },
            forecast: {
                type: "array",
                items: {
                    type: "string"
                },
                description: "Описание погодных условий"
            },
            error: {
                type: "string",
                description: "Возвращается при возникновении ошибки. Содержит описание ошибки"
            }
        }
    }
}

const resp = await giga.chat({
  messages: [
    {
      role: "user",
      content: "Погода в Манжероке на три дня",
    },
  ],
  functions: [
    {"name": 'text2image',},
    weatherForecast
  ],
  function_call: 'auto'
});

console.log(resp.choices[0]?.message);

Сохранение контекста

Независимо от того, обратилась модель к встроенной функции или нет, ее ответ будет содержать идентификатор functions_state_id. Для сохранения контекста передавайте этот идентификатор в соответствующих сообщениях с ролью assistant:

{
    "messages": [
        {
            "role": "user",
            "content": "Нарисуй корову"
        },
        {
            "content": "Добавил в очередь на генерацию изображения... <img src=\"4919dd7a-b97b-4ed9-8db0-5aa68f2bf24b\" fuse=\"true\"/> — вот такая корова у меня получилась.",
            "role": "assistant",
            "functions_state_id": "77d3fb14-457a-46ba-937e-8d856156d003"
        },
        {
            "content": "А теперь нарисуй слона",
            "role": "user"
        }
    ],
    "model": "GigaChat"
}

Потоковая генерация токенов

Работа встроенных функций может занимать продолжительное время. Вы можете обрабатывать ответ модели по мере его создания с помощью потоковой генерации токенов (параметр запроса "stream": true).

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

• cURL
• Python
• JS/TS

curl -L -X POST 'https://gigachat.devices.sberbank.ru/api/v1/chat/completions' \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-H 'Authorization: Bearer <токен_доступа>' \
--data-raw '{
  "model": "GigaChat-Pro",
  "messages": [
    {
      "role": "system",
      "content": "Ты — Василий Кандинский"      
    },
    {
      "role": "user",
      "content": "Нарисуй розового кота"
    }
  ],
  "function_call": "auto",
  "stream": true,
}'

Пример ответа:

data: {"choices":[{"delta":{"content":"осталось 00:11","role":"function_in_progress","name":"text2image"},"index":0}],"created":1733401362,"model":"GigaChat-Max:1.0.26.20","object":"chat.completion"}

data: {"choices":[{"delta":{"content":"осталось 00:06","role":"function_in_progress","name":"text2image"},"index":0}],"created":1733401367,"model":"GigaChat-Max:1.0.26.20","object":"chat.completion"}

data: {"choices":[{"delta":{"content":"осталось 00:03","role":"function_in_progress","name":"text2image"},"index":0}],"created":1733401370,"model":"GigaChat-Max:1.0.26.20","object":"chat.completion"}

data: {"choices":[{"delta":{"content":"осталось 00:01","role":"function_in_progress","name":"text2image"},"index":0}],"created":1733401372,"model":"GigaChat-Max:1.0.26.20","object":"chat.completion"}

data: {"choices":[{"delta":{"content":"осталось 00:01","role":"function_in_progress","name":"text2image"},"index":0}],"created":1733401373,"model":"GigaChat-Max:1.0.26.20","object":"chat.completion"}

data: {"choices":[{"delta":{"content":"<img src=\"6fb0b045-e4c8-43b6-bd4d-06eb6cf267eb\" fuse=\"true\"/> вот иллюстрация Красной Шапочки.","role":"assistant"},"index":0}],"created":1733401374,"model":"GigaChat-Max:1.0.26.20","object":"chat.completion"}

data: {"choices":[{"delta":{"content":"","functions_state_id":"1a7f916c-053b-4649-9c7d-0ce0f4a0f515"},"index":0,"finish_reason":"stop"}],"created":1733401374,"model":"GigaChat-Max:1.0.26.20","object":"chat.completion","usage":{"prompt_tokens":24,"completion_tokens":48,"total_tokens":72,"precached_prompt_tokens":0}}

data: [DONE]

Запуск потоковой генерации с помощью SDK:

import asyncio
import time

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

payload = Chat(
    messages=[
        Messages(
            role=MessagesRole.SYSTEM,
            content="Ты — Василий Кандинский.",
        ),
        Messages(
            role=MessagesRole.USER,
            content="Нарисуй розового кота",
        ),
    ],
    update_interval=0.1,
    function_call="auto",
)


async def main():
    async with GigaChat(credentials="<ключ_авторизации>", verify_ssl_certs=False) as giga:
        async for chunk in giga.astream(payload):
            print(time.time(), chunk, flush=True)


if __name__ == "__main__":
    asyncio.run(main())

Пример ответа:

1738844827.437161 x_headers={'x-request-id': '732bef07-bbb6-4658-8739-5c79f0c53b13', 'x-session-id': '3a46eb04-eb73-4ed8-bd5e-3d106a8b32cd', 'x-client-id': None} choices=[ChoicesChunk(delta=MessagesChunk(role=<MessagesRole.ASSISTANT: 'assistant'>, content='<img src="7f1add5a-cf5e-4956-b2bc-2e113d220953" fuse="true"/> вот такой розовый кот у меня получился.', function_call=None), index=0, finish_reason=None)] created=1738844827 model='GigaChat:1.0.26.20' object_='chat.completion'
1738844827.437387 x_headers={'x-request-id': '732bef07-bbb6-4658-8739-5c79f0c53b13', 'x-session-id': '3a46eb04-eb73-4ed8-bd5e-3d106a8b32cd', 'x-client-id': None} choices=[ChoicesChunk(delta=MessagesChunk(role=None, content='', function_call=None), index=0, finish_reason='stop')] created=1738844827 model='GigaChat:1.0.26.20' object_='chat.completion'

Запуск потоковой генерации с помощью партнерского пакета langchain-gigachat:

from langchain_gigachat.chat_models import GigaChat
from langchain_core.prompts import ChatPromptTemplate, MessagesPlaceholder

llm = GigaChat(
    credentials="<ключ_авторизации>",
    verify_ssl_certs=False,
)

# Метод `bind_tools(tools=[], tool_choice="auto")` сообщает модели, что нужно использовать встроенные функции.
llm = llm.bind_tools(tools=[], tool_choice="auto")

# Промпт для создания изображения
prompt = ChatPromptTemplate.from_messages(
    [
        (
            "system",
            """Ты — Василий Кандинский.""",
        ),
        ("user", """{topic}"""),
    ]
)

# Цепочка для создания изображения
generate_image_chain = prompt | llm

for chunk in generate_image_chain.stream({"topic": "Нарисуй розового кота"}):
  print(chunk)

Пример ответа:

content='<img src="b62726bb-0cf5-4980-a8c4-70f3e4a6cc9b" fuse="true"/> вот рисунок розового кота.' additional_kwargs={'image_uuid': 'b62726bb-0cf5-4980-a8c4-70f3e4a6cc9b', 'postfix_message': ' вот рисунок розового кота.'} response_metadata={'x_headers': {'x-request-id': '4c723683-053d-4568-84cc-6cf1307f2742', 'x-session-id': 'f1f874cb-4d29-4ae1-9d5b-b17b70ffa86f', 'x-client-id': None}} id='4c723683-053d-4568-84cc-6cf1307f2742'
content='' additional_kwargs={} response_metadata={'finish_reason': 'stop'} id='4c723683-053d-4568-84cc-6cf1307f2742'

Обращение к функции с помощью SDK:

import { GigaChat } from 'gigachat';

const giga = new GigaChat({
    credentials: '<ключ_авторизации>',
});

let message = "";
let bit = "";
let n = 0;
for await (const chunk of giga.stream(
    {
  messages: [
    {
      role: "user",
      content: "Нарисуй розового кота",
    },
  ],
  function_call: 'auto'
}
)) {
    bit = chunk.choices[0];
    message += chunk.choices[0];
    n++;
    console.log('\nФрагмент ' + n + ': ' , bit);
}

Обращение к функции с помощью партнерского пакета langchain-gigachat:

import { GigaChat } from "langchain-gigachat"
import { HumanMessage, SystemMessage } from "@langchain/core/messages";

const llm = new GigaChat({
  credentials: '<ключ_авторизации>',
});

const messages = [
  new SystemMessage("Ты — Василий Кандинский."),
  new HumanMessage("Нарисуй розового кота и напиши короткую историю про него"),
];

const llmWithFunctions = llm.bindTools([], {tool_choice: 'auto'});

const stream = await llmWithFunctions.stream(messages);
const chunks = [];
for await (const chunk of stream) {
  chunks.push(chunk);
  console.log(`${chunk.content}|`);
}

Сообщения о запуске встроенной функции будут приходить с ролью function_in_progress. Они будут содержать данные о времени начала обработки, оставшемся времени до окончания работы функции и ее наименовании.