Миграция приложения на Node.js OpenAI SDK: Base URL, стриминг и триаж с участием человека

Миграция существующего Node.js-приложения со стандартных эндпоинтов OpenAI API на OpenAI-совместимый прокси или единый шлюз не требует переписывания бизнес-логики. Поскольку официальная Node.js-библиотека openai предоставляет конфигурацию сетевых адресов и заголовков на уровне клиента, вы можете перенаправить трафик, отслеживать использование и применять альтернативную маршрутизацию без замены используемого SDK.

Тем не менее маршрутизация через прокси или шлюз добавляет ряд практических нюансов: управление заголовками аутентификации, обработка потоковых событий (streaming) по HTTP, диагностика граничных ошибок и гарантия того, что автономные действия модели остаются под контролем человека. В сценариях триажа тикетов службы поддержки — когда модель классифицирует входящие запросы, готовит черновики ответов и предлагает действия по тикету — контроль со стороны оператора перед выполнением бизнес-логики имеет решающее значение.

В этом руководстве показано, как перенастроить Node.js OpenAI SDK для работы с OpenAI-совместимым шлюзом вроде OneMux, настроить стриминг предложений по триажу и внедрить обязательное подтверждение человеком перед выполнением ответственных операций.

---

Архитектура: триаж поддержки с участием человека

Автоматизированный триаж клиентских обращений включает анализ входящего тикета, оценку тональности пользователя, определение срочности и выработку рекомендаций по дальнейшим шагам (например, подготовка ответа, назначение тегов или частичный возврат средств). Как отмечено в OpenAI Agents Guide, агентные архитектуры, вызывающие реальные побочные эффекты во внешних системах, надежнее строить с сохранением цикла оркестрации внутри кода приложения — там, где можно удерживать защитные барьеры и точки согласования.

Вместо того чтобы наделять модель полномочиями прямого исполнения, пайплайн триажа делится на две независимые фазы:

1. Анализ и формирование предложений (AI Execution): модель обрабатывает сообщение пользователя, передает в потоковом режиме внутреннее обоснование и черновик ответа, а также формирует структурированный вызов инструмента (tool call) с предлагаемыми действиями.
2. Утверждение и диспетчеризация (Application Execution): приложение приостанавливает выполнение рабочего процесса, сохраняет предложение в очереди на проверку и ожидает подтверждения от оператора службы поддержки перед изменением статуса тикета или отправкой сообщения клиенту.

Incoming Ticket ──> Node.js Service ──> OneMux Gateway ──> Model Inference
                                                                 │
                                                                 ▼
Ticket Updated  <── Support Agent  <── Review Queue  <── Proposed Actions
   (Execution)        (Approves)       (Intercepted)       & Draft Stream

---

Настройка Node.js SDK: Base URL и аутентификация

Официальный npm-пакет openai позволяет перенаправлять запросы на любой совместимый эндпоинт путем изменения свойства baseURL. Подобрать подходящую модель можно в каталоге моделей OneMux.

Сначала установите официальный пакет:

npm install openai

Чтобы направить запросы в OneMux, инициализируйте экземпляр клиента с вашим API-ключом OneMux и базовым URL https://api.onemux.net/v1:

import OpenAI from 'openai';

// Initialize the OpenAI client pointing to the OneMux gateway
const client = new OpenAI({
  apiKey: process.env.ONEMUX_API_KEY,
  baseURL: 'https://api.onemux.net/v1',
});

Проверка аутентификации

При проксировании через шлюз поведение ошибок аутентификации имеет свои особенности. Если API-ключ отсутствует, недействителен или на балансе платформы недостаточно средств, клиент выбросит AuthenticationError (HTTP 401). Перед запуском задач триажа в продакшене проверьте корректность учетных данных по руководству по быстрому старту OneMux.

---

Реализация стриминга для черновиков триажа в реальном времени

Операторам поддержки удобнее видеть генерируемые черновики ответов инкрементально, не дожидаясь формирования полного ответа. При вызове chat.completions.create с параметром stream: true SDK возвращает асинхронный итерируемый поток, передающий Server-Sent Events (SSE).

Следующая реализация выводит черновик ответа в стандартный поток вывода (или в интерфейс оператора) и параллельно собирает структурированные вызовы инструментов для категоризации обращения:

import OpenAI from 'openai';

const client = new OpenAI({
  apiKey: process.env.ONEMUX_API_KEY,
  baseURL: 'https://api.onemux.net/v1',
});

interface TriageProposal {
  draftResponse: string;
  category?: string;
  priority?: 'low' | 'medium' | 'high' | 'urgent';
  suggestedRefundAmount?: number;
}

export async function triageTicketStream(
  ticketId: string,
  customerMessage: string
): Promise<TriageProposal> {
  const tools: OpenAI.ChatCompletionTool[] = [
    {
      type: 'function',
      function: {
        name: 'propose_ticket_action',
        description: 'Propose triage tags, priority updates, or billing adjustments.',
        parameters: {
          type: 'object',
          properties: {
            category: {
              type: 'string',
              enum: ['billing', 'technical_bug', 'account_access', 'general'],
            },
            priority: {
              type: 'string',
              enum: ['low', 'medium', 'high', 'urgent'],
            },
            suggestedRefundAmount: {
              type: 'number',
              description: 'Refund amount in USD if the user experienced downtime.',
            },
          },
          required: ['category', 'priority'],
        },
      },
    },
  ];

  const stream = await client.chat.completions.create({
    model: 'gpt-4o',
    stream: true,
    tools,
    messages: [
      {
        role: 'system',
        content:
          'You are a support triage assistant. Analyze the ticket, stream a helpful draft reply for the customer, and call propose_ticket_action with triage metadata.',
      },
      {
        role: 'user',
        content: customerMessage,
      },
    ],
  });

  let draftResponse = '';
  let toolCallArguments = '';
  let toolName = '';

  for await (const chunk of stream) {
    const delta = chunk.choices[0]?.delta;

    // Stream conversational draft chunks
    if (delta?.content) {
      draftResponse += delta.content;
      process.stdout.write(delta.content);
    }

    // Accumulate tool call chunks
    if (delta?.tool_calls) {
      for (const toolCall of delta.tool_calls) {
        if (toolCall.function?.name) {
          toolName = toolCall.function.name;
        }
        if (toolCall.function?.arguments) {
          toolCallArguments += toolCall.function.arguments;
        }
      }
    }
  }

  let parsedAction = {};
  if (toolName === 'propose_ticket_action' && toolCallArguments) {
    try {
      parsedAction = JSON.parse(toolCallArguments);
    } catch (err) {
      console.error('Failed to parse tool call JSON payload:', err);
    }
  }

  return {
    draftResponse,
    ...parsedAction,
  };
}

---

Барьер согласования человеком (Human Approval Gate)

Автономное выполнение вызовов инструментов может привести к несанкционированным возвратам средств или необоснованной эскалации приоритета. Приложение должно сохранять сгенерированный объект TriageProposal в промежуточном хранилище (например, запись в базе данных со статусом PENDING_APPROVAL), а не выполнять действия мгновенно.

interface PendingReviewTicket {
  ticketId: string;
  status: 'PENDING_APPROVAL' | 'APPROVED' | 'REJECTED';
  proposal: TriageProposal;
}

// Step 1: Queue the proposal for human verification
async function queueForHumanReview(ticketId: string, proposal: TriageProposal) {
  console.log(`[Review Queue] Storing proposal for ticket ${ticketId}:`, proposal);
  // Persistence logic: await db.triageReviews.create({ ticketId, proposal, status: 'PENDING_APPROVAL' });
}

// Step 2: Human operator action handler
async function handleHumanDecision(
  reviewId: string,
  decision: 'APPROVE' | 'REJECT',
  modifiedProposal?: Partial<TriageProposal>
) {
  if (decision === 'REJECT') {
    console.log(`Review ${reviewId} rejected by operator.`);
    return;
  }

  // Execute business logic only after approval
  console.log(`Review ${reviewId} approved. Executing refund and priority assignment...`);
  // e.g., await paymentGateway.issueRefund(modifiedProposal.suggestedRefundAmount);
}

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

---

Диагностика ошибок: разграничение сбоев клиента, шлюза и апстрима

При использовании OpenAI-совместимого шлюза вроде OneMux сбои могут происходить на трех уровнях: в коде вашего локального приложения, на прокси-шлюзе или на стороне конечного провайдера модели. Анализ стандартного экземпляра APIError из SDK openai позволяет точно локализовать первопричину:

import OpenAI from 'openai';

try {
  await triageTicketStream('ticket-101', 'System is down since morning!');
} catch (error) {
  if (error instanceof OpenAI.APIError) {
    console.error(`Status Code: ${error.status}`);
    console.error(`Error Message: ${error.message}`);
    console.error(`Error Code: ${error.code}`);
    console.error(`Error Type: ${error.type}`);

    switch (error.status) {
      case 401:
        console.error('Check your OneMux API key in environment variables.');
        break;
      case 402:
        console.error('Account balance exhausted. Top up credits in the dashboard.');
        break;
      case 429:
        console.error('Rate limit reached or concurrent request ceiling exceeded.');
        break;
      case 502:
      case 504:
        console.error('Upstream model provider timeout or network disruption via gateway.');
        break;
      default:
        console.error('Unhandled API exception.');
    }
  } else {
    console.error('Non-API runtime error:', error);
  }
}

Разбор типичных статус-кодов

---

Ограничения и непротестированные параметры

Хотя OneMux обеспечивает прямую совместимость со стандартными эндпоинтами OpenAI Chat Completion (/v1/chat/completions), учитывайте следующие технические ограничения:

1. Расширенные бета-эндпоинты: эндпоинты за пределами базовых сценариев генерации текста, эмбеддингов и чата — такие как изолированные окружения (code interpreter sandboxes) или управляемые примитивы рантайма Assistants API, описанные в документации OpenAI, — требуют явной поддержки шлюзом. Перед развертыванием сверяйтесь с документацией используемого шлюза.
2. Передача пользовательских заголовков: кастомные заголовки организаций или проектов (OpenAI-Organization, OpenAI-Project) могут игнорироваться или обрабатываться прокси иначе. Убедитесь, что токен аутентификации передается через стандартный заголовок Bearer.
3. Управление состоянием: если вы планируете мигрировать с hosted OpenAI Assistants API на собственный цикл управления агентом внутри приложения, ответственность за хранение истории сессий и персистентность полностью ложится на ваше Node.js-приложение.

---

Заключение

Перенос работающего Node.js-приложения на базе OpenAI SDK на OpenAI-совместимый шлюз выполняется минимальными усилиями: достаточно изменить параметр baseURL, передать соответствующий API-ключ шлюза и скорректировать логирование ошибок с учетом статус-кодов промежуточного сервиса. Изолируя предложения модели от прямых побочных эффектов с помощью барьера подтверждения, ваш конвейер триажа обращений сохранит высокую скорость работы, исключив непреднамеренные действия.

---

Источники

• OpenAI Agents Guide: https://developers.openai.com/api/docs/guides/agents
• Документация для разработчиков OneMux: https://onemux.net/docs