Базовый URL кастомного провайдера в Vercel AI SDK: заметки по настройке Flatkey

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

Это руководство предназначено для разработчиков, команд по продуктам ИИ, инженеров платформ, создателей автоматизации, финансовых операторов и специалистов по закупкам, использующих AI SDK в маршруте Next.js, серверном действии, воркере, очереди или цикле агента. Оно было обновлено 29 июня 2026 года на основе текущей документации AI SDK, проверки типов по текущим пакетам AI SDK и общедоступных страниц Flatkey. Фрагменты кода являются шаблонами. В этой задаче не был доступен действующий API-ключ Flatkey, поэтому выполните дымовые тесты с вашим собственным ключом, текущим базовым URL консоли Flatkey и псевдонимами моделей, включенными для вашей учетной записи.

Краткий ответ: базовый URL кастомного провайдера в Vercel AI SDK

Для настройки базового URL кастомного провайдера в Vercel AI SDK с Flatkey начните с официального пакета провайдера, совместимого с OpenAI. Создайте провайдер с помощью createOpenAICompatible, установите baseURL на текущий базовый URL Flatkey из вашей консоли, установите apiKey на ваш ключ Flatkey и используйте псевдонимы моделей Flatkey в generateText или streamText.

npm install ai @ai-sdk/openai-compatible zod

export FLATKEY_API_KEY="fk_your_key"
export FLATKEY_BASE_URL="https://console.flatkey.ai/v1" # Скопируйте текущее значение из Flatkey
export FLATKEY_MODEL="your-flatkey-model-alias"

import { createOpenAICompatible } from '@ai-sdk/openai-compatible';
import { generateText } from 'ai';

function requiredEnv(name: string): string {
  const value = process.env[name];
  if (!value) {
    throw new Error(`Отсутствует ${name}`);
  }
  return value;
}

const flatkey = createOpenAICompatible({
  name: 'flatkey',
  apiKey: requiredEnv('FLATKEY_API_KEY'),
  baseURL: requiredEnv('FLATKEY_BASE_URL'),
  includeUsage: true,
});

const result = await generateText({
  model: flatkey.chatModel(requiredEnv('FLATKEY_MODEL')),
  prompt: 'Ответьте одной короткой проверкой маршрутизации Flatkey AI SDK.',
});

console.log(result.text);
console.log(result.finishReason);
console.log(result.usage);
console.log(result.warnings);

Это минимальная рабочая конфигурация для миграции базового URL кастомного провайдера в Vercel AI SDK. Не останавливайтесь на этом. Успешный текстовый ответ доказывает только то, что один формат запроса достиг одного псевдонима модели. Это не доказывает работоспособность потоковой передачи, инструментов, структурированного вывода, видимости затрат, поведения квот или отката.

Что поддерживается в текущей документации AI SDK

Текущая документация AI SDK предлагает два релевантных пути. Пакет провайдера, совместимого с OpenAI, создан для провайдеров, которые реализуют OpenAI API. Он предоставляет createOpenAICompatible с опциями, включающими name, apiKey, baseURL, headers, queryParams, кастомный fetch, includeUsage, supportsStructuredOutputs, преобразования тела запроса и извлечение метаданных.

Пакет провайдера OpenAI также поддерживает createOpenAI({ baseURL }) для индивидуальных настроек, включая прокси-серверы. Провайдер, совместимый с OpenAI, является более чистым вариантом по умолчанию для базового URL кастомного провайдера в Vercel AI SDK, поскольку его имя провайдера, кастомное извлечение метаданных, специфичные для провайдера опции и имена фабрик моделей предназначены для маршрутов, совместимых с OpenAI, но не являющихся OpenAI.

Свежие данные о Flatkey, которые следует использовать с осторожностью

На главной странице Flatkey, проверенной 29 июня 2026 года, указан заголовок One API gateway for production AI teams и мета-описание, в котором говорится, что Flatkey объединяет доступ к моделям, маршрутизацию, биллинг, аналитику использования и операционный контроль. API цен в реальном времени вернул 633 строки моделей, 23 поставщика и семейства конечных точек для /v1/chat/completions, /v1/responses, /v1/messages, /v1beta/models/{model}:generateContent, /v1/images/generations и /v1/video/generations.

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

Базовый URL и настройка окружения

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

function requiredEnv(name: string): string {
  const value = process.env[name];
  if (!value) {
    throw new Error(`Missing ${name}`);
  }
  return value;
}

const flatkey = createOpenAICompatible({
  name: 'flatkey',
  apiKey: requiredEnv('FLATKEY_API_KEY'),
  baseURL: requiredEnv('FLATKEY_BASE_URL'),
  includeUsage: true,
});

Затем отделите маршрутизацию рабочей нагрузки от настройки транспорта. Базовый URL указывает SDK, куда отправлять запросы. Псевдоним модели определяет, какой маршрут Flatkey и вышестоящую модель вы запрашиваете.

const MODEL_ROUTES = {
  supportTriage: 'FLATKEY_SUPPORT_MODEL',
  workflowPlanning: 'FLATKEY_PLANNING_MODEL',
  codeReview: 'FLATKEY_CODE_MODEL',
  fallback: 'FLATKEY_FALLBACK_MODEL',
} as const;

function modelFor(routeName: keyof typeof MODEL_ROUTES) {
  return flatkey.chatModel(requiredEnv(MODEL_ROUTES[routeName]));
}

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

Сначала проведите дымовое тестирование для не-потокового текста

Начните с generateText. Он возвращает простой объект результата с текстом, причиной завершения, данными об использовании, предупреждениями, шагами и метаданными ответа. Используйте его для проверки аутентификации, формата базового URL, псевдонима модели и видимости данных об использовании перед тестированием потоковой передачи или инструментов.

import { generateText } from 'ai';

const result = await generateText({
  model: modelFor('supportTriage'),
  prompt: 'Reply with one short migration readiness check.',
});

console.log({
  text: result.text,
  finishReason: result.finishReason,
  usage: result.usage,
  warnings: result.warnings,
});

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

Тестируйте потоковую передачу отдельно

У потоковой передачи другие сценарии сбоев. Она затрагивает потоковую передачу ответов, тайм-ауты бессерверных функций, отмену в пользовательском интерфейсе, обработку ошибок и учет использования. В документации AI SDK показаны streamText, result.textStream, колбэк onError и промисы результата, такие как result.usage. Провайдер, совместимый с OpenAI, также имеет includeUsage для потоковой передачи метаданных ответа, если провайдер это поддерживает.

import { streamText } from 'ai';

const stream = streamText({
  model: flatkey.chatModel(requiredEnv('FLATKEY_MODEL')),
  prompt: 'Stream three short setup checks.',
  onError({ error }) {
    console.error(error);
  },
});

for await (const textPart of stream.textStream) {
  process.stdout.write(textPart);
}

const usage = await stream.usage;
console.log({ usage });

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

Проверьте вызовы инструментов с тем же псевдонимом

API инструментов AI SDK использует объект tools, хелпер tool, inputSchema и опциональную функцию execute. Простой чат-запрос не является подтверждением для вызова инструментов. Сначала протестируйте небольшую схему, а затем расширьте ее до набора инструментов, который действительно используют ваши агенты.

import { generateText, isStepCount, tool } from 'ai';
import { z } from 'zod';

const result = await generateText({
  model: flatkey.chatModel(requiredEnv('FLATKEY_TOOL_MODEL')),
  tools: {
    routeReadiness: tool({
      description: 'Return the readiness state for a Flatkey route.',
      inputSchema: z.object({
        routeName: z.string().describe('Internal route name to inspect'),
      }),
      execute: async ({ routeName }) => ({
        routeName,
        checked: true,
      }),
    }),
  },
  stopWhen: isStepCount(2),
  prompt: 'Use the tool for route supportTriage.',
});

console.log(result.toolCalls);
console.log(result.toolResults);
console.log(result.usage);

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

Когда использовать createOpenAI вместо этого

Если ваше приложение уже повсеместно использует @ai-sdk/openai, опция baseURL провайдера OpenAI может стать путем миграции с меньшими изменениями. Это все еще настройка базового URL кастомного провайдера в Vercel AI SDK, но вам следует быть более явными в выборе API модели.

import { createOpenAI } from '@ai-sdk/openai';
import { generateText } from 'ai';

const flatkeyViaOpenAIProvider = createOpenAI({
  name: 'flatkey',
  apiKey: requiredEnv('FLATKEY_API_KEY'),
  baseURL: requiredEnv('FLATKEY_BASE_URL'),
});

const result = await generateText({
  model: flatkeyViaOpenAIProvider.chat(requiredEnv('FLATKEY_MODEL')),
  prompt: 'Reply with one short OpenAI-provider base URL check.',
});

В текущей документации провайдера OpenAI говорится, что Responses является API по умолчанию для провайдера OpenAI начиная с AI SDK 5, если вы не укажете маршрут, например, .chat(...). Именно поэтому в приведенном выше примере явно используется .chat(...). Если вы собираетесь тестировать семейство конечных точек Flatkey /v1/responses, рассматривайте это как отдельную проверку маршрута с отдельным псевдонимом модели и путем отката.

Контрольный список для настройки

Типичные сценарии сбоев

Как это руководство соотносится с другими руководствами Flatkey

Если вам нужен более широкий путь миграции, начните с руководства по миграции на OpenAI-совместимый API. Для смежных шаблонов настройки инструментов ознакомьтесь с руководством по настройке Cherry Studio API и руководством по cc-switch Claude Code Flatkey. Используйте цены Flatkey, чтобы изучить текущий каталог моделей, а затем получите ключ, когда будете готовы запустить дымовые тесты в своем собственном аккаунте.

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

Как установить базовый URL кастомного провайдера Vercel AI SDK для Flatkey?

Создайте OpenAI-совместимый провайдер с помощью createOpenAICompatible, установите baseURL на текущий базовый URL Flatkey, установите apiKey на ваш ключ Flatkey и передайте псевдоним модели Flatkey в generateText или streamText.

Что мне использовать: @ai-sdk/openai-compatible или @ai-sdk/openai?

Используйте @ai-sdk/openai-compatible для новой настройки Flatkey, так как он предназначен для OpenAI-совместимых провайдеров. Используйте @ai-sdk/openai с createOpenAI({ baseURL }), когда ваше приложение уже стандартизировано на провайдере OpenAI и вы хотите, чтобы изменения в коде были минимальными.

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

Используйте значение, отображаемое в вашей текущей консоли Flatkey. В большинстве шаблонов SDK, совместимых с OpenAI, базовый URL включает префикс версии, чтобы вызовы SDK могли корректно добавлять пути, такие как /chat/completions.

Может ли один базовый URL Flatkey маршрутизировать несколько моделей?

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

Были ли протестированы эти фрагменты кода AI SDK?

Фрагменты кода прошли проверку типов 29 июня 2026 года на соответствие ai@7.0.4, @ai-sdk/openai-compatible@3.0.1, @ai-sdk/openai@4.0.2, TypeScript и Zod. Они не были выполнены с использованием Flatkey, так как в этой среде выполнения не было доступного действующего API-ключа Flatkey.

Итог

Миграция на кастомный базовый URL провайдера в Vercel AI SDK должна представлять собой небольшое изменение в провайдере, но с серьезным списком проверок. Используйте createOpenAICompatible для провайдера Flatkey, храните базовый URL и псевдонимы моделей в конфигурации, сначала протестируйте текст без потоковой передачи, отдельно протестируйте потоковую передачу и вызовы инструментов, подтвердите наличие данных об использовании в Flatkey и держите наготове план отката до тех пор, пока производственный трафик не стабилизируется. Когда проверки будут готовы, получите ключ и запустите дымовые тесты с вашими собственными псевдонимами моделей.