# Руководство GigaChat API для LLM
> Краткое руководство по работе с GigaChat API, которое предназначено для использования с LLM.
> Используйте его для создания контекста при работе с AI-помощниками.
> Руководство содержит краткое описание моделей, базовые примеры работы с различными функциями API, примеры запуска потоковой генерации и работы с функциями.
## Сертификаты Минцифры
Для работы с GigaChat API нужно установить корневые сертификаты Минцифры.
В противном случае API будет возвращать ошибку проверки сертификатов, например:
```sh
[SSL: CERTIFICATE_VERIFY_FAILED] certificate verify failed: self-signed certificate in certificate chain
```
Для установки сертификатов выполните команду:
```sh
curl -k "https://gu-st.ru/content/lending/russian_trusted_root_ca_pem.crt" -w "\n" >> $(python -m certifi)
```
## Модели
### Модели для генерации
| Название модели | Значение поля `model` | Размер контекста в токенах | Поддержка функций | Описание |
| --------------- | --------------------- | -------------------------- | ----------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
| GigaChat 2 Lite | `GigaChat-2` | 128 тыс. | да | Быстрая и легкая модель для простых повседневных задач |
| GigaChat 2 Pro | `GigaChat-2-Pro` | 128 тыс. | да | Усовершенствованная модель для ресурсоемких задач, обеспечивающая максимальную эффективность в обработке данных, креативности и соблюдении инструкций |
| GigaChat 2 Max | `GigaChat-2-Max` | 128 тыс. | да | Мощная модель для самых сложных и масштабных задач, требующих высочайшего уровня креативности и качества исполнения |
### Модели для создания эмбеддингов
| Название модели | Значение поля `model` | Размер контекста в токенах | Описание |
| -------------------- | -------------------------- | ----------------------------------- | --------------------------------------------------------------------------- |
| Embeddings | `Embeddings` | 512 | Базовая модель, доступная по умолчанию для векторного представления текстов |
| Embeddings-2 | `Embeddings-2` | 512 | Доработанная и улучшенная версия базовой модели Embeddings |
| EmbeddingsGigaR | `EmbeddingsGigaR` | 4096 | Продвинутая модель с большим размером контекста |
| GigaEmbeddings-3B-2025-09 | `GigaEmbeddings-3B-2025-09` | 4096 |Развитая модель для создания векторного представления текста |
## Работа с API
### Запросы на генерацию
#### Пример простого запроса
Запрос:
```python
from gigachat import GigaChat
from gigachat.models import Chat, Messages, MessagesRole
import os
giga = GigaChat(
credentials=os.environ.get("GIGACHAT_CREDENTIALS"),
scope=os.environ.get("GIGACHAT_SCOPE"),
model="GigaChat-2-Max"
)
history=Chat(
messages=[
Messages(
role=MessagesRole.USER,
content="Привет! Меня зовут Василий."
)
]
)
response = giga.chat(history)
print(response)
```
#### Передача истории чата
Модель не хранит историю сообщений.
Чтобы модель учитывала контекст диалога в своих ответах, нужно передавать все сообщения с соответствующими ролями:
* роль `system` — системный промпт. Передается один раз в первом сообщении;
* роль `assistant` — сообщение модели;
* роль `user` — сообщение пользователя.
```python
from gigachat import GigaChat
from gigachat.models import Chat, Messages, MessagesRole
import os
giga = GigaChat(
credentials=os.environ.get("GIGACHAT_CREDENTIALS"),
scope=os.environ.get("GIGACHAT_SCOPE"),
model="GigaChat-2-Max"
)
history=Chat(
messages=[
Messages(
role=MessagesRole.SYSTEM,
content="Отвечай пользователю на английском языке."
),
Messages(
role=MessagesRole.USER,
content="Привет! Меня зовут Василий."
),
Messages(
role=MessagesRole.ASSISTANT,
content="Привет, Василий!"
),
Messages(
role=MessagesRole.USER,
content="Напомни, как меня зовут?"
)
]
)
response = giga.chat(history)
print(response)
```
#### Генерация изображений
Генерация изображений выполняется с помощью встроенной функции `text2image` в ответ на промпт, который содержит указание на то, что нужно сгенерировать изображение.
В запросе нужно явно задать автоматический режим работы — `function_call="auto"`.
Пример:
```python
from gigachat import GigaChat
from gigachat.models import Chat, Messages, MessagesRole
import os
giga = GigaChat(
credentials=os.environ.get("GIGACHAT_CREDENTIALS"),
scope=os.environ.get("GIGACHAT_SCOPE"),
model="GigaChat-2-Max"
)
payload = Chat(
messages=[
Messages(
role=MessagesRole.SYSTEM,
content="Ты — Василий Кандинский"
),
Messages(
role=MessagesRole.USER,
content="Нарисуй розового кота"
)
],
function_call="auto",
)
response = giga.chat(payload)
print(response.choices[0].message.content)
```
Сгенерированное изображение сохранится в хранилище файлов, а ответ будет содержать его идентификатор:
```html
```
Используйте идентификатор, чтобы скачать изображение.
#### Генерация 3D-моделей
Генерация 3D-моделей выполняется с помощью встроенной функции `text2model3d` в ответ на промпт, который содержит указание на то, что нужно сгенерировать модель.
В запросе нужно явно передать название функции и задать автоматический режим работы — `function_call="auto"`.
Пример:
```python
from gigachat import GigaChat
from gigachat.models import Chat, Messages, MessagesRole, Function
import os
giga = GigaChat(
credentials=os.environ.get("GIGACHAT_CREDENTIALS"),
scope=os.environ.get("GIGACHAT_SCOPE"),
model="GigaChat-2-Max",
# Повышение времени ожидания, так как создание модели — длительный процесс
timeout=200
)
payload = Chat(
messages=[Messages(role=MessagesRole.USER, content="Сгенерируй 3D-модель шара")],
function_call="auto",
functions=[
Function(name="text2model3d")
]
)
response = giga.chat(payload)
print (response)
```
Сгенерированная модель сохранится в хранилище файлов, а ответ будет содержать ее идентификатор::
```html
Модель шара успешно создана. Представляю тебе реалистичный трехмерный шар.
```
Используйте идентификатор, чтобы скачать модель.
### Работа с файлами
Модели GigaChat умеют обрабатывать текстовые документы, изображения или аудио, и использовать их при генерации ответов. Для этого вы можете загрузить необходимые файлы в хранилище и передать запрос с идентификатором файла в выбранную модель GigaChat. При генерации ответа модель будет учитывать указанные файлы.
Сгенерированные моделями файлы также сохраняются в хранилище.
В хранилище можно сохранять файлы форматов:
* текстовые документы — `txt`, `doc`, `docx`, `pdf`, `epub`, `ppt`, `pptx`;
* изображения — `jpeg`, `png`, `tiff`, `bmp`;
* аудиофайлы — `mp4`, `mp3`, `m4a`, `wav`, `weba`, `ogg`, `opus`.
Максимальный размер одного файла в запросе:
* текстовый документ — 40 Мб,
* изображение — 15 Мб;
* аудиофайл — 35 Мб.
Общий размер загружаемых аудиофайлов и изображений должен быть меньше 80 Мб.
#### Загрузка файла в хранилище
Пример:
```python
from gigachat import GigaChat
import os
giga = GigaChat(
credentials=os.environ.get("GIGACHAT_CREDENTIALS"),
scope=os.environ.get("GIGACHAT_SCOPE"),
model="GigaChat-2-Max"
)
response = giga.upload_file(open("/<путь_к_файлу>/<имя_файла>.txt", mode="rb"))
print(response)
```
### Получение списка доступных файлов
Пример:
```py
from gigachat import GigaChat
with GigaChat(
credentials="ключ_авторизации",
verify_ssl_certs=False
) as client:
files = client.get_files()
for file in files.data:
print(f"{file.id_}: {file.filename}")
```
### Просмотр информации о файле
Пример:
```py
from gigachat import GigaChat
with GigaChat(
credentials="ключ_авторизации",
verify_ssl_certs=False
) as client:
single_file = client.get_file("<идентификатор_файла>")
print(f"{single_file}")
```
### Удаление файла
Пример:
```py
from gigachat import GigaChat
with GigaChat() as client:
client.delete_file("<идентификатор_файла>")
```
#### Распознавание изображений
Для распознавания изображений в массиве attachments нужно передать идентификатор соответствующего изображения в хранилище файлов:
```python
result = giga.chat(
{
"messages": [
{
"role": "user",
"content": "Какой окрас у кота на фото?",
"attachments": ["<идентификатор_файла_в_хранилищще>"],
}
],
"temperature": 0.1
}
)
```
#### Обработка текстовых документов
Для генерации с помощью загруженного текстового документа передайте его идентификатор в массиве `attachments`.
Одновременно можно использовать только один документ.
Если вы передадите несколько идентификаторов файлов, для генерации будет использован только первый документ из списка.
```python
from gigachat import GigaChat
import os
giga = GigaChat(
credentials=os.environ.get("GIGACHAT_CREDENTIALS"),
scope=os.environ.get("GIGACHAT_SCOPE"),
model="GigaChat-2-Max"
)
result = giga.chat(
{
"function_call": "auto",
"messages": [
{
"role": "user",
"content": "На чем основана твоя работа? Отвечай на основе приложенного документа",
"attachments": ["1460d895-2b26-4ce0-8b0d-cc7665a969df"],
}
],
"temperature": 0.1
}
)
print(result.choices[0].message.content)
```
#### Скачивание файлов
Пример:
```python
import base64
from gigachat import GigaChat
from gigachat.models import Image
def get_image(file_path: str = './giga_img.jpg'):
with GigaChat(credentials="<ключ_авторизации>") as giga:
response: Image = giga.get_image(file_id="<идентификатор_файла_в_хранилище>")
# Сохранить изображение в файл
with open(file_path, mode="wb") as fd:
fd.write(base64.b64decode(response.content))
```
## Работа с функциями
Функции — это внешние инструменты, к которым могут обращаться модели GigaChat для решения задач пользователей.
Они незаменимы при построении сложных решений с применением LLM, таких, как AI-агенты и ассистенты.
Модели не исполняют функции самостоятельно, а принимают решения о работе с ними, опираясь на имеющиеся знания, текущий разговор и описание функций из запроса.
Режим обращения к функциям задается с помощью поля `function_call`, который может принимать значения:
* `none` — отключение обращения к функциям;
* `auto` — в авторежиме модель, ориентируясь на содержание сообщений, принимает решение: воспользоваться одной из встроенных функций или сгенерировать аргументы для пользовательских функций из массива `functions`. При этом, если массив содержит описание хотя бы одной пользовательской функции, модель сможет ее вызвать только если ее название передано в массиве `functions`;
* `{"name": "название_функции"}` — принудительная генерация аргументов для указанной функции. При принудительной генерации аргументов для пользовательской функции ее описание нужно обязательно передавать в массиве `functions`. В противном случае вернется ошибка.
### Встроенные функции GigaChat API
Моделям доступны функции:
* `text2image`
Генерация изображения в формате JPEG.
* `get_file_content`
Использование текстовых документов для генерации ответа.
* `text2model3d`
Генерация модели в формате FBX.
### Пользовательские функции
При принятии решения о генерации аргументов модель ориентируется на описание функции в поле `description`.
Чем подробнее описана функция, тем лучше будет результат работы модели при работе с ней.
Пример описания функции прогноза погоды:
```json
{
"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": "Возвращается при возникновении ошибки. Содержит описание ошибки"
}
}
},
"status": {
"description": "Статус",
"enum": [
"success",
"fail"
],
"type": "string"
}
}
```
Описание функции включает поля:
* `name` — обязательное поле с названием функции;
* `description` — подробное текстовое описание того, как работает функция. Модель анализирует запрос и доступные описания, после чего принимает решение о генерации параметров для подходящей функции.
* `parameters` — обязательное поле. Содержит массив с описанием аргументов функции, которые может сгенерировать модель.
* `few_shot_examples` — массив, в котором вы можете описать примеры того, как модель должна сгенерировать аргументы. Наличие примеров повышает качество генерации аргументов.
* `return_parameters` — объект с описанием ответа, который модель будет ожидать в ответе от функции.
### Пример генерации аргументов для пользовательской функции
```python
from gigachat import GigaChat
from gigachat.models import Chat, Function, Messages, MessagesRole, FunctionParameters
from gigachat.models.few_shot_example import FewShotExample
import os
giga = GigaChat(
credentials=os.environ.get("GIGACHAT_CREDENTIALS"),
scope=os.environ.get("GIGACHAT_SCOPE"),
model="GigaChat-2-Max"
)
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"],
few_shot_examples=[FewShotExample(
request="Какая погода в Москве в ближайшие три дня",
params={"location": "Moscow, Russia", "format": "celsius", "num_days": "3"}
)],
return_parameters=[{ "type": "object", "properties": {"location": {"type": "string", "description": "Местоположение, например, название города"}, "temperature": {"type": "integer", "description": "Температура для заданного местоположения"}, "forecast": {"type": "array", "items": {"type": "string"}, "description": "Описание погодных условий"}, "error": {"type": "string", "description": "Возвращается при возникновении ошибки. Содержит описание ошибки"}}}]
)
)
payload = Chat(
messages=[Messages(role=MessagesRole.USER, content="погода в Манжероке на десять дней")],
functions=[weather_forecast_function]
)
response = giga.chat(payload)
print(response)
```
## Потоковая передача токенов
Режим получения потока токенов поможет обрабатывать ответ GigaChat по мере его генерации.
При включении этого режима GigaChat передает токены в потоке коротких сообщений, формат которых соответствует протоколу Server-Sent Events.
События передаются с типом `text/event-stream`.
Последним в потоке приходит событие `data: [DONE]`.
Пример запроса:
```python
from gigachat import GigaChat
for chunk in GigaChat(credentials="<ключ_авторизации>").stream("Напиши смешной рассказ про кота и слона."):
print(chunk.choices[0].delta.content, end="", flush=True)
```
Пример ответа:
```text
data: {"choices":[{"delta":{"content":"GigaChat is a service capable of interacting with the user in a dialogue format, writing code, and creating texts and images upon the user's request.","role":"assistant"},"index":0}],"created":1754637655,"model":"GigaChat:2.0.28.2","object":"chat.completion"}
data: {"choices":[{"delta":{"content":""},"index":0,"finish_reason":"stop"}],"created":1754637655,"model":"GigaChat:2.0.28.2","object":"chat.completion","usage":{"prompt_tokens":56,"completion_tokens":31,"total_tokens":87,"precached_prompt_tokens":3}}
data: [DONE]
```
## Создание эмбеддингов
Для создания эмбеддингов (векторного представления текста) доступны две модели: `Embeddings` и `EmbeddingsGigaR`.
```python
from gigachat import GigaChat
with GigaChat() as client:
result = client.embeddings(["Привет, мир!", "Машинное обучение интересно"], model="EmbeddingsGigaR")
for i, item in enumerate(result.data):
print(f"Текст {i + 1}: {len(item.embedding)} измерений")
```