Задача кейса — за вечер собрать Telegram-бота, который отвечает на вопросы пользователей с помощью языковой модели. Telegram отвечает за доставку сообщений, модель — за текст ответа. Heli даёт OpenAI-совместимый endpoint, поэтому подойдёт стандартная библиотека openai для Python: меняются только base URL и ключ, а оплата идёт в рублях с баланса Heli.
Что понадобится
- Токен бота от @BotFather (команда /newbot).
- Ключ Heli: регистрация на getheli.ru с подтверждением почты или вход через Google / Яндекс ID, затем «Создать ключ» на вкладке «Ключи» кабинета.
- Python 3.10+ и библиотеки
python-telegram-bot(v20+) иopenai.
Код бота
Бот работает в режиме long polling, поэтому не нужен ни домен, ни вебхук. Используем асинхронный клиент AsyncOpenAI: обработчики python-telegram-bot асинхронные, и синхронный вызов блокировал бы ответы другим пользователям.
import os
from openai import AsyncOpenAI, APIStatusError, APITimeoutError
from telegram import Update
from telegram.ext import Application, CommandHandler, ContextTypes, MessageHandler, filters
client = AsyncOpenAI(
base_url="https://getheli.ru/v1",
api_key=os.environ["HELI_API_KEY"],
timeout=60,
)
MODEL = os.environ.get("HELI_MODEL", "google/gemini-3.5-flash")
SYSTEM = "Ты вежливый ассистент поддержки. Отвечай кратко и по делу."
async def start(update: Update, context: ContextTypes.DEFAULT_TYPE) -> None:
await update.message.reply_text("Привет! Задайте вопрос.")
async def answer(update: Update, context: ContextTypes.DEFAULT_TYPE) -> None:
try:
resp = await client.chat.completions.create(
model=MODEL,
messages=[
{"role": "system", "content": SYSTEM},
{"role": "user", "content": update.message.text or ""},
],
max_tokens=600,
)
text = resp.choices[0].message.content or "Пустой ответ модели."
except APITimeoutError:
text = "Модель долго отвечает, попробуйте ещё раз."
except APIStatusError as err:
# 401 — ключ, 402 — баланс, 404 — слаг модели
text = f"Ошибка API ({err.status_code}). Сообщите администратору."
await update.message.reply_text(text[:4000])
def main() -> None:
app = Application.builder().token(os.environ["TELEGRAM_BOT_TOKEN"]).build()
app.add_handler(CommandHandler("start", start))
app.add_handler(MessageHandler(filters.TEXT & ~filters.COMMAND, answer))
app.run_polling()
if __name__ == "__main__":
main()pip install "python-telegram-bot>=20" openai
export HELI_API_KEY="sk-heli-ВАШ_КЛЮЧ"
export TELEGRAM_BOT_TOKEN="123456:ABC..."
python bot.pyОтвет обрезается до 4000 символов: у Telegram ограничение 4096 символов на сообщение. Ключи храните в переменных окружения, а не в коде и не в репозитории.
Как развивать дальше
- Память диалога. Храните последние 6–10 сообщений в
context.chat_dataи передавайте их вmessages; длинную историю обрезайте, иначе каждый ответ будет дороже. - Защита баланса. Ограничьте число запросов на пользователя в минуту и задайте лимит расходов ключа в разделе «Лимиты» кабинета.
- Запуск на сервере. Оформите бота как systemd-сервис или Docker-контейнер с переменными окружения — перезапуск после сбоя будет автоматическим.
Какую модель выбрать
Для бота поддержки важнее скорость и цена, чем глубина рассуждений. Gemini 3.5 Flash и GPT-5.4 mini отвечают быстро и недорого. Если бот разбирает сложные вопросы по документам, переключите HELI_MODEL на Claude Sonnet 5 — код менять не нужно. Подробнее — в статье «Какую модель выбрать для чат-бота».
Частые ошибки
- 401 — неверный или отозванный ключ Heli; проверьте переменную
HELI_API_KEY. - 402 insufficient_balance — закончился баланс; бот начнёт отвечать сразу после пополнения.
- Модель не найдена — опечатка в слаге или нет префикса вендора; сверьте с
GET /v1/models. - Таймауты — уменьшите
max_tokens, выберите более быструю модель или увеличьтеtimeoutклиента.
Формат запросов — в документации Heli, пополнение баланса — в разделе «Оплата».
Попробуйте Heli
Ключ sk-heli- появляется после подтверждения почты. Через Google и Яндекс — сразу в кабинете.