7 тестов для миграции перед сменой базового URL AI API

Тесты миграции базового URL AI API должны проводиться до изменения переменных окружения, а не после того, как производственный трафик начнет сбоить. Изменение одного baseURL или base_url может одновременно перенести аутентификацию, выбор модели, потоковую передачу, вызов инструментов, записи об использовании, поведение квот и управление откатом на новый путь.

Flatkey предназначен для команд, которым нужен один ключ, один совместимый с OpenAI уровень маршрутизации, а также более прозрачный биллинг и обзор использования по разным поставщикам моделей. На главной странице Flatkey, проверенной 7 июля 2026 года, был показан пример маршрута https://router.flatkey.ai/v1/chat/completions, в то время как текущие страницы моделей и цен предоставляли для ознакомления контекст модели, конечной точки, поставщика и биллинга. Рассматривайте эти страницы как свидетельство на день миграции, а затем проведите собственные дымовые тесты учетной записи перед переносом трафика.

Используйте это руководство как практическую последовательность тестов для миграции базового URL AI API. Цель не в том, чтобы проверить каждый путь приложения. Цель — доказать работоспособность наименьшего безопасного пути через новый базовый URL, а затем добавлять функции по одному уровню за раз.

7 тестов для миграции базового URL AI API

Выполняйте тесты в этом порядке. Каждый из них должен предоставить доказательства, которые можно прикрепить к тикету на развертывание.

Не пропускайте ранние тесты из-за того, что обертка фреймворка уже работала в промежуточной среде. Большинство тестов миграции базового URL AI API проваливаются, потому что SDK молча считывает другой ключ, получает неверный корневой базовый URL или отправляет валидную модель не тому семейству конечных точек.

Тест 1: Аутентификация и композиция базового URL

Начните вне приложения. Вам нужно доказать, что ключ и базовый URL могут достичь простейшей формы конечной точки.

Распространенная ошибка с базовым URL — передача полного пути конечной точки в SDK. Для SDK, совместимого с OpenAI, базовый URL обычно является корнем API, например https://router.flatkey.ai/v1, а SDK добавляет /chat/completions, /responses или другую конечную точку. Передача https://router.flatkey.ai/v1/chat/completions в качестве базового URL может привести к дублированию пути.

Сначала используйте отредактированную проверку окружения:

test -n "$FLATKEY_API_KEY" && echo "FLATKEY_API_KEY is set"
printf '%s' "$FLATKEY_API_KEY" | wc -c
printf '%s\n' "$FLATKEY_BASE_URL"

Затем сделайте один прямой запрос:

export FLATKEY_BASE_URL="https://router.flatkey.ai/v1"
export FLATKEY_MODEL="your-current-flatkey-model-alias"

curl -sS "$FLATKEY_BASE_URL/chat/completions" \
  -H "Authorization: Bearer $FLATKEY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "'"$FLATKEY_MODEL"'",
    "messages": [
      {"role": "user", "content": "Ответьте в точности: base url ok"}
    ]
  }'

Если это вернет 401, исправьте ключ и заголовок аутентификации перед сменой моделей. Если вернется 404, проверьте хост, корень /v1 и не был ли продублирован путь конечной точки. Если вернется 403, проверьте учетную запись, проект, модель, регион или политику IP. Документация по кодам ошибок OpenAI трактует 401 как аутентификацию, 429 как превышение лимита запросов или квоты, а 500 или 503 как проблемы с сервером или его перегрузку; шлюз может добавить больше деталей, поэтому сохраните тело ответа.

Тест 2: Каталог моделей и семейство конечных точек

Совместимый с OpenAI базовый URL не делает каждое имя модели переносимым. У OpenAI API есть конечная точка для получения списка моделей (List models), а его конечные точки Chat Completions и Responses используют разные форматы запросов. Шлюз или маршрут, совместимый с провайдером, может предоставлять модель для одного семейства конечных точек, но не для другого.

Прежде чем изменять производственную конфигурацию, создайте небольшую карту моделей:

Условие прохождения теста — не «имя модели выглядит правильно». Условие прохождения заключается в том, что текущая консоль Flatkey, каталог моделей или каталог провайдера показывают точный псевдоним для того семейства конечных точек, которое вы планируете вызывать. Свяжите эту работу с вашим общим управлением моделями с помощью руководства по именам моделей, совместимых с OpenAI.

Тест 3: Простое завершение чата

Третий тест миграции базового URL AI API — это самый маленький реальный запрос на генерацию. Он должен быть непотоковым. Не включайте инструменты, JSON-схему, файлы, изображения, повторные попытки или промежуточное ПО приложения.

Сохраните:

Если простой запрос не удался, пока не отлаживайте потоковую передачу. Сначала используйте руководство по устранению неполадок API, совместимого с OpenAI, чтобы выявить проблемы с ключом, маршрутом, семейством конечных точек и псевдонимом модели.

Тест 4: Паритет SDK

После того как curl заработает, докажите, что SDK строит тот же маршрут. Текущая официальная документация OpenAI направляет разработчиков к официальным SDK для JavaScript и Python. В сборнике рецептов OpenAI также показано использование пользовательских конечных точек, где клиент создается с токеном и пользовательским базовым URL. При миграции сделайте это явным в коде, вместо того чтобы полагаться на оставшиеся значения OPENAI_API_KEY или OPENAI_BASE_URL.

Шаблон для Python:

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["FLATKEY_API_KEY"],
    base_url=os.environ.get("FLATKEY_BASE_URL", "https://router.flatkey.ai/v1"),
)

response = client.chat.completions.create(
    model=os.environ["FLATKEY_MODEL"],
    messages=[{"role": "user", "content": "Reply with exactly: sdk ok"}],
)

print(response.choices[0].message.content)
print(response.usage)

Шаблон для Node:

import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.FLATKEY_API_KEY,
  baseURL: process.env.FLATKEY_BASE_URL ?? "https://router.flatkey.ai/v1",
});

const response = await client.chat.completions.create({
  model: process.env.FLATKEY_MODEL!,
  messages: [{ role: "user", content: "Reply with exactly: sdk ok" }],
});

console.log(response.choices[0]?.message?.content);
console.log(response.usage);

Записывайте в лог разрешенный базовый URL при запуске процесса, но не записывайте ключ. Если curl выполняется успешно, а SDK — нет, проверьте приоритет переменных окружения, версию SDK, объединение путей, заголовки организации/проекта и поведение прокси, прежде чем менять модель.

Тест 5: Потоковая передача или SSE

Потоковая передача — это та область, где многие миграции выглядят успешно на уровне HTTP, но терпят неудачу в приложении. Справочник по Chat Completions от OpenAI возвращает либо JSON-объект, либо потоковые фрагменты завершения чата, когда потоковая передача включена. Responses API также может возвращать text/event-stream с именами событий, которые отличаются от фрагментов Chat Completions.

Выполните это после того, как заработает непотоковый запрос:

curl -N "$FLATKEY_BASE_URL/chat/completions" \
  -H "Authorization: Bearer $FLATKEY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "'"$FLATKEY_MODEL"'",
    "stream": true,
    "messages": [
      {"role": "user", "content": "Count from one to five slowly."}
    ]
  }'

Условия прохождения:

Для более глубокого анализа потока сравните с существующим тестом потоковой передачи SSE, совместимой с OpenAI.

Тест 6: Вызов инструментов или функций

Вызов инструментов добавляет риски, связанные со схемой и возможностями. Руководство OpenAI по вызову функций описывает многоэтапный процесс: отправка инструментов, получение вызова инструмента, выполнение кода приложения, возврат вывода инструмента, а затем получение окончательного ответа модели. Миграция базового URL может завершиться неудачей на любом из этих этапов, даже если простой текст работает.

Не начинайте с полного набора ваших производственных инструментов. Используйте одну крошечную функцию:

{
  "model": "your-current-flatkey-model-alias",
  "messages": [
    {"role": "user", "content": "Use the tool for order A123."}
  ],
  "tools": [
    {
      "type": "function",
      "function": {
        "name": "lookup_order",
        "description": "Возвращает статус тестового заказа.",
        "parameters": {
          "type": "object",
          "properties": {
            "order_id": {"type": "string"}
          },
          "required": ["order_id"],
          "additionalProperties": false
        }
      }
    }
  ],
  "tool_choice": "auto"
}

Если это не удается, в то время как обычный чат работает, вы больше не отлаживаете базовый URL. Вы отлаживаете возможности модели, семейство конечных точек, строгость схемы, tool_choice или поддержку шлюза для выбранного маршрута. Опубликованное руководство по совместимости вызова инструментов охватывает более широкий список провайдеров.

Тест 7: Использование, квоты и откат

Заключительные тесты миграции базового URL AI API являются операционными. Сгенерированного ответа недостаточно, если финансовый отдел не может его сверить, квоты ведут себя не так, как ожидалось, или откат требует экстренного изменения кода.

После одного успешного дымового теста проверьте:

Используйте файл отката, который достаточно прост для выполнения в стрессовой ситуации:

# активный
AI_API_BASE_URL=https://router.flatkey.ai/v1
AI_API_MODEL=your-current-flatkey-model-alias

# откат
AI_API_BASE_URL_ROLLBACK=https://previous-provider.example/v1
AI_API_MODEL_ROLLBACK=previous-production-model
AI_API_ROLLBACK_OWNER=platform-oncall

Не полагайтесь на память для отката. Храните предыдущую конфигурацию, флаг функции, команду развертывания и команду проверки в том же тикете развертывания, что и тесты миграции базового URL AI API.

Пакет доказательств, который следует сохранить

Для каждой среды храните один пакет, который отвечает на следующие вопросы:

В этом заключается практическое преимущество проведения тестов миграции базового URL AI API перед переключением. Артефакт полезен для обзора развертывания, реагирования на инциденты, сверки использования и в качестве доказательства для отдела закупок.

Какую роль играет Flatkey

Flatkey может уменьшить разрастание миграции за счет централизации доступа к моделям, маршрутизации, биллинга, аналитики использования и операционного обзора под одним ключом. Это не отменяет необходимости тестирования. Это дает команде единую точку контроля, где разработка, финансы и эксплуатация могут проверять одни и те же доказательства по маршруту.

Перед миграцией ознакомьтесь с актуальными страницами моделей Flatkey и цен, подтвердите текущий базовый URL консоли и начните с одного небольшого теста маршрута. Если вы все еще планируете более широкое переключение, используйте это руководство вместе с руководством по миграции API, совместимых с OpenAI. Когда вы будете готовы провести собственные тесты, получите ключ и сделайте первый запрос достаточно маленьким, чтобы его можно было проверить вручную.

Часто задаваемые вопросы

Что такое тесты миграции базового URL AI API?

Тесты миграции базового URL AI API — это проверки перед переключением, которые доказывают, что новый корень API работает для аутентификации, маршрутизации моделей, обычного чата, использования SDK, потоковой передачи, инструментов, считывания данных об использовании, поведения квот и отката.

Что следует тестировать в первую очередь: curl или SDK?

Сначала протестируйте curl. Curl доказывает работоспособность ключа, URL, пути конечной точки и псевдонима модели без учета поведения фреймворка. Затем протестируйте SDK с теми же значениями.

Должен ли базовый URL включать /chat/completions?

Обычно нет. Предоставьте SDK корень API, например /v1, а затем позвольте SDK добавить конечную точку. Используйте полную конечную точку только для прямых запросов curl.

Почему потоковая передача не работает, когда обычный чат работает?

Потоковая передача может не работать, потому что маршрут буферизует ответы, клиентский парсер ожидает неверную форму события, промежуточное ПО потребляет поток или выбранное семейство конечных точек не поддерживает используемую вами форму потока.

Что делать, если я пока не могу выполнять живые запросы к Flatkey?

Сохраняйте фрагменты кода в качестве шаблонов, проверяйте публичную документацию и конфигурацию консоли и не переводите производственный трафик, пока реальный ключ не докажет успешное прохождение семи тестов миграции базового URL AI API в вашей собственной среде.

Итог

Смена базового URL AI API — это производственная миграция, а не простое редактирование строки. Выполните тесты миграции базового URL AI API в следующем порядке: аутентификация, каталог моделей, простой чат, паритет SDK, потоковая передача, инструменты, а также использование и откат. Когда все семь тестов пройдены успешно, смена базового URL становится контролируемым переключением, а не сеансом поздней отладки.