OpenAI-совместимый API: как подключить LLM к Python

Если сервис говорит, что поддерживает OpenAI API, это обычно означает: к нему можно обращаться знакомым форматом запросов, но не обязательно всеми возможностями OpenAI. Для Python удобнее всего оставить официальный пакет openai, а заменить адрес сервера и имя модели.

Что именно нужно заменить

У клиента есть три независимые настройки:

• api_key — ключ выбранного сервиса;
• base_url — базовый адрес его API;
• model — идентификатор модели, который этот сервис принимает.

Для совместимого endpoint первые две настройки не обязаны иметь отношение к OpenAI. В частности, путь /v1 иногда уже входит в base_url, а иногда его нужно добавить по документации провайдера. Угадывать здесь опаснее, чем открыть пример curl у сервиса: лишний или пропущенный сегмент даст ошибку маршрута ещё до проверки модели.

Официальный Python-клиент OpenAI поддерживает переопределение адреса через base_url и переменную окружения OPENAI_BASE_URL — это именно настройка клиента, а не гарантия того, что любой endpoint реализует весь API. Документация openai-python о настройке HTTP-клиента

Установка и переменные окружения

Текущая версия официального клиента требует Python 3.10 или новее. Создайте виртуальное окружение и установите пакет:

python -m venv .venv

source .venv/bin/activate

python -m pip install -U openai

В Windows PowerShell вместо команды активации используйте .venv\Scripts\Activate.ps1.

Ключ и адрес положите в окружение, а не в файл программы. Например, в Linux/macOS:

export LLM_API_KEY="ключ-вашего-сервиса"
export LLM_BASE_URL="https://provider.example/v1"
export LLM_MODEL="имя-модели-из-документации"

В PowerShell синтаксис такой:

$env:LLM_API_KEY = "ключ-вашего-сервиса"
$env:LLM_BASE_URL = "https://provider.example/v1"
$env:LLM_MODEL = "имя-модели-из-документации"

Не коммитьте эти значения в .py, .env или логи CI. Если используете .env, добавьте файл в .gitignore; для постоянного приложения подойдёт менеджер секретов. Ключ нужен не только OpenAI: облачный совместимый провайдер проверяет собственный ключ по своим правилам. Требования к аутентификации OpenAI API

Минимальный запрос через официальный клиент

Наиболее переносимый контракт здесь — Chat Completions: передать model и массив messages, затем прочитать choices[0].message.content.

import os

from openai import OpenAI


client = OpenAI(
    api_key=os.environ["LLM_API_KEY"],
    base_url=os.environ["LLM_BASE_URL"],
)

response = client.chat.completions.create(
    model=os.environ["LLM_MODEL"],
    messages=[
        {"role": "user", "content": "Ответь одним словом: работает ли запрос?"}
    ],
)

text = response.choices[0].message.content
if not text or not text.strip():
    raise RuntimeError("API вернул пустой текстовый ответ")

print(text.strip())

В примере нет конкретного URL, ключа или модели намеренно: их выдаёт выбранный провайдер. Важно, чтобы модель была доступна именно вашему ключу, а endpoint принимал маршрут Chat Completions. Форма ответа с choices[0].message.content показана в документации Ollama как пример OpenAI-совместимого API; у другого сервиса могут быть ограничения по полям или иной набор поддержанных ресурсов. Пример совместимости Ollama

Проверка на непустой строке полезнее, чем print(response). Она ловит ситуацию, когда HTTP-запрос формально успешен, но приложение не получило текста в ожидаемом месте. Это ещё не полная сертификация совместимости, а проверка минимального контракта, который вы собираетесь использовать.

Как читать типичные ошибки

401 Unauthorized обычно означает неправильный ключ или неподходящий способ аутентификации. Для локального сервера ключ может требоваться только потому, что официальный клиент ожидает значение api_key; сервер при этом способен его игнорировать. Такое поведение допустимо для локальной разработки, но переносить его на облачный провайдер нельзя.

404 Not Found чаще связан с base_url: проверьте, не потерялся ли /v1, не добавлен ли он дважды и соответствует ли путь документации конкретного сервиса.

400 с сообщением о модели означает, что запрос дошёл до endpoint, но значение model ему неизвестно или модель недоступна вашему ключу. Скопируйте идентификатор из списка моделей или из примера провайдера, включая регистр и все суффиксы.

Если сервер отвечает ошибкой на поле messages, temperature или другую опцию, сначала уберите необязательные параметры. Совместимость — это подмножество API, а не обещание полной идентичности с OpenAI. Поэтому не следует автоматически переносить на такой endpoint Responses API, tools, vision, streaming или embeddings: каждую возможность нужно проверить в его документации.

Отдельно о доступе к зарубежным сервисам

После настройки endpoint может понадобиться доступ к зарубежному цифровому сервису для разработки или тестирования. Для такого отдельного заказа можно посмотреть каталог оплаты зарубежных цифровых сервисов Amber Market: магазин подтверждает оплату через СБП, автоматических списаний нет. Перед заказом проверьте на странице конкретной услуги товар, срок, доступные способы оплаты и итоговую сумму.

Это не пополнение OpenAI API и не выдача API-ключа. Ключ и баланс API остаются у выбранного LLM-провайдера; каталог решает другую задачу — оплату подходящей цифровой услуги по подтверждённым условиям.

Что считать успешной проверкой

Минимальный тест пройден, если одновременно выполняются четыре условия:

1. Python версии 3.10 или новее запускает программу.
2. Клиент принимает base_url и подключается к нужному хосту.
3. Провайдер принимает ключ и указанную модель.
4. В response.choices[0].message.content приходит непустой текст.

После этого можно добавлять обработку таймаутов, повторов и логирование метаданных ответа. Но сначала зафиксируйте рабочие значения адреса, модели и минимального тела запроса. Повторить запрос после обрыва связи легко; сложнее понять, успел ли сервер выполнить первую попытку. Если вызов запускает платную генерацию, схема повторов должна учитывать риск двойного выполнения.