Обращение к встроенным функциям
Встроенные функции — это функции, которые исполняются внутри сервиса 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": "