Стоимость подключения GLM API ниже, чем многие ожидают: он предоставляет OpenAI-совместимый интерфейс, и существующему OpenAI SDK обычно достаточно изменить три вещи — API-ключ, Base URL и имя модели. Настоящие ловушки не в том, «получится ли вызвать», а в том, действует ли имя модели, как обрабатывать потоковый вывод, в каком формате приходят вызовы инструментов и какие параметры нельзя переносить из OpenAI без изменений.
Ниже минимальный запрос, который проходит всю цепочку, затем стриминг, вызов инструментов, разбор ошибок и чек-лист миграции. Все примеры можно запустить, подставив свой ключ.
Примечание: Zhipu, GLM и BigModel — товарные знаки их правообладателей; статья носит технический характер и не подразумевает аффилированность, агентские или лицензионные отношения с Zhipu. Base URL, имена моделей, длина контекста и правила тарификации могут меняться; сверяйтесь с официальной документацией открытой платформы Zhipu и страницей тарифов.
1. Подготовка
Перед началом проверьте три вещи:
- Рабочий API-ключ, тип которого соответствует вызываемому интерфейсу.
- Правильный Base URL: официальный адрес и адрес шлюза нельзя смешивать.
- Актуальное действующее имя модели, а не пример из старой статьи.
Для нового проекта сначала проверьте аутентификацию и сеть через curl, затем подключайте SDK. Так при ошибке проще понять, в чём дело: в ключе, адресе или коде.
2. Как заполнить Base URL
Официальный OpenAI-совместимый интерфейс Zhipu обычно указывается так:
https://open.bigmodel.cn/api/paas/v4
OpenAI-совместимый адрес ZSQH AI Gateway:
https://ai.zhongshangqihang.com/v1
Оба используют путь OpenAI /chat/completions. Не дублируйте в коде версию или /chat/completions и не смешивайте варианты с косой чертой и без неё на конце.
| Способ подключения | Пример Base URL | Когда подходит | Что учесть |
|---|---|---|---|
| Официальный Zhipu | https://open.bigmodel.cn/api/paas/v4 |
Только GLM, нужны новейшие функции | Нужны официальный аккаунт и баланс |
| ZSQH AI Gateway | https://ai.zhongshangqihang.com/v1 |
Единый вход к нескольким моделям, единый счёт | Нужно создать ключ в шлюзе |
3. Как выбрать имя модели
Серия GLM делится по возможностям на текстовые, визуальные, речевые и векторные модели. У текстовых есть разные уровни: одни ориентированы на универсальный диалог и агентов, другие — на низкую задержку и высокий параллелизм, третьи поддерживают более длинный контекст. На примере текущей серии GLM-5 в документации встречаются glm-5.3, glm-5.3-flash, glm-5.2 и другие, но модели обновляются; фактически доступные имена смотрите в консоли и на странице тарифов.
Не выбирайте только «самую сильную». Для вопросов поддержки и пакетной классификации уровень с низкой задержкой часто выгоднее; для анализа длинных документов и сложных агентов берите старший. Храните имя модели в конфигурации, а не в коде — тогда переключение будет проще.
Если задача связана с пониманием изображений, выбирайте модель с визуальным входом; для векторного поиска — серию embedding. Пути и параметры текстовых, визуальных и векторных моделей различаются, не подставляйте одно тело запроса везде. Перед запуском прогоните кандидатов на одном наборе оценки, сравните точность, задержку и расход, затем определите основную и резервную модели.
4. Первый вызов через curl
Сначала задайте переменную окружения, чтобы ключ не попал в историю команд:
export GLM_API_KEY="your_key_here"
curl https://open.bigmodel.cn/api/paas/v4/chat/completions \
-H "Authorization: Bearer $GLM_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "glm-5.3",
"messages": [
{"role": "system", "content": "Ты краткий технический ассистент."},
{"role": "user", "content": "Объясни в трёх предложениях, что такое API-шлюз."}
],
"temperature": 0.6
}'
При нормальном ответе смотрите три поля: choices[0].message.content — ответ, usage — расход, finish_reason — причина завершения. При 401 проверьте ключ и заголовок; при 1211 — имя модели.
5. Python SDK и потоковый вывод
Нужен OpenAI SDK версии 1.0 или выше. После указания Base URL вызов почти такой же, как у OpenAI:
import os
from openai import OpenAI
client = OpenAI(
api_key=os.getenv("GLM_API_KEY"),
base_url="https://open.bigmodel.cn/api/paas/v4",
)
stream = client.chat.completions.create(
model="glm-5.3",
messages=[{"role": "user", "content": "Напиши описание продукта не длиннее ста слов."}],
stream=True,
)
for chunk in stream:
if chunk.choices and chunk.choices[0].delta.content:
print(chunk.choices[0].delta.content, end="", flush=True)
В потоковом выводе первый chunk может содержать только роль, а content будет пустым; не предполагайте текст в каждом chunk. При включённом режиме размышления рассуждения могут приходить в поле reasoning_content, а итоговый ответ — в content; обрабатывайте их раздельно, чтобы не показывать процесс рассуждения конечным пользователям.
6. Вызов инструментов и различия параметров
Вызов инструментов использует формат OpenAI tools и tool_choice. После того как модель вернула message.tool_calls, разберите function.arguments каждого вызова как JSON, выполните локальную функцию и верните результат сообщением с ролью tool. В production проверяйте параметры и контролируйте тайм-ауты: нельзя слепо доверять сгенерированным моделью аргументам.
При миграции с OpenAI обратите внимание на различия: диапазон temperature обычно от 0 до 1, значение 0 может не действовать; значение по умолчанию около 0.6; часть новых возможностей передаётся через extra_body. Точные параметры — в официальной документации совместимости.
В потоковом сценарии нужно обрабатывать отключение клиента. Если пользователь закрыл страницу, сервер должен как можно быстрее отменить upstream-запрос, чтобы не продолжать генерацию и списание; если результат обязан быть полным, переведите задачу в фоновую очередь, а не полагайтесь на соединение фронтенда.
7. Типичные ошибки
| Симптом | Возможная причина | Что делать |
|---|---|---|
| 401 / 1000 | Неверный ключ, несовпадение типа | Сверить тип ключа и заголовок запроса |
| 1211 | Имя модели не существует или не открыто | Проверить доступные модели в консоли |
| 1261 | Вход превышает лимит контекста | Сжать промпт или разбить на части |
| 1302 / 1305 | Ограничение аккаунта или перегрузка платформы | Снизить параллелизм, повторять с задержкой |
| 1113 | Задолженность по аккаунту | Пополнить баланс и повторить |
| Тайм-аут соединения | DNS, прокси или сетевой маршрут | Сначала локализовать сеть через curl |
Повторы помогают только при 429, 5xx и сетевых тайм-аутах. Ошибки 401, 1211 и 1261 от повтора не исчезнут, а только потратят время и квоту.
8. Чек-лист миграции с OpenAI
- Сохраните текущие промпты, параметры моделей и набор оценки.
- Создайте отдельный ключ для GLM, не используйте ключи других поставщиков.
- Вынесите Base URL и имя модели в конфигурацию.
- Сравните качество, задержку и расход на одном наборе примеров.
- Проверьте совместимость разбора стриминга, вызова инструментов и JSON-вывода.
- Настройте повторы, тайм-ауты и параллелизм, наблюдайте неделю и только затем переключайте весь трафик.
9. Частые вопросы
GLM API полностью совместим с OpenAI?
Большинство распространённых интерфейсов совместимы, но остаются различия в диапазонах параметров, полях размышления и части продвинутых возможностей. Проверяйте по официальной документации совместимости, не считайте поведение всех параметров одинаковым.
Нужна ли косая черта в конце Base URL?
В официальной документации встречаются оба варианта, SDK обычно обрабатывает их сам. Главное — не дублировать путь; выберите один вариант и придерживайтесь его в проекте.
Можно ли получить процесс рассуждения в потоковом выводе?
Часть моделей в режиме размышления возвращает reasoning_content. Показывать ли его, зависит от продукта; конечным пользователям обычно показывают только итоговый ответ.
Формат вызова инструментов такой же, как у OpenAI?
Определение инструментов и структура ответа в основном повторяют формат OpenAI, но детали параметров могут меняться от модели к модели. Перед запуском проведите регрессию с реальными инструментами.
Имена моделей у официального провайдера и шлюза одинаковые?
В большинстве случаев используется один набор имён, но доступность конкретной модели и поддержку параметра проверяйте в консоли шлюза и на странице тарифов.
