Di chuyển ứng dụng Node.js OpenAI SDK: Base URL, Streaming và Phân loại hỗ trợ có con người can thiệp (Human-in-the-Loop)

Việc chuyển đổi một ứng dụng Node.js sẵn có từ các endpoint trực tiếp của OpenAI sang một proxy hoặc unified gateway tương thích OpenAI không đòi hỏi bạn phải viết lại toàn bộ logic cốt lõi. Do thư viện openai chính thức cho Node.js cung cấp cấu hình ở cấp độ client cho network origins và headers, bạn hoàn toàn có thể chuyển hướng lưu lượng, theo dõi mức độ sử dụng và tận dụng cơ chế định tuyến thay thế mà không cần đổi SDK.

Tuy nhiên, việc định tuyến qua proxy hoặc gateway sẽ phát sinh một số vấn đề thực tế: quản lý authentication headers, xử lý các sự kiện streaming qua HTTP, chẩn đoán lỗi ở lớp edge, và đảm bảo kết quả từ mô hình tự hành luôn nằm dưới sự giám sát của con người. Trong quy trình phân loại hỗ trợ khách hàng (customer support triage)—nơi mô hình AI tiếp nhận ticket, phân loại độ khẩn cấp, soạn thảo phản hồi và đề xuất hành động xử lý—việc bắt buộc có sự kiểm duyệt của con người trước khi thực thi logic nghiệp vụ là vô cùng quan trọng.

Hướng dẫn này minh họa cách cấu hình lại Node.js OpenAI SDK cho một gateway tương thích OpenAI như OneMux, stream các đề xuất phân loại và áp dụng cơ chế phê duyệt thủ công trước khi thực hiện các tác vụ quan trọng.

---

Kiến trúc: Phân loại hỗ trợ có con người phê duyệt

Quy trình phân loại hỗ trợ khách hàng tự động bao gồm việc đọc ticket gửi đến, đánh giá cảm xúc người dùng, xác định mức độ khẩn cấp và đề xuất các bước tiếp theo (chẳng hạn như soạn phản hồi, gắn tag hoặc cấp khoản bồi hoàn một phần). Như được phác thảo trong OpenAI Agents Guide, các kiến trúc agent có tác động trực tiếp đến thế giới thực sẽ vận hành tốt nhất khi vòng lặp điều phối (orchestration loop) nằm trực tiếp trong mã nguồn ứng dụng, nơi bạn có thể duy trì các rào chắn an toàn (guardrails) và điểm kiểm duyệt.

Thay vì trao toàn quyền thực thi cho mô hình, pipeline phân loại được tách thành hai giai đoạn rõ rệt:

1. Phân tích và Đề xuất (AI Execution): Mô hình xử lý tin nhắn của người dùng, stream phần phân tích lý do nội bộ kèm bản thảo câu trả lời, đồng thời tạo một tool call có cấu trúc để đề xuất các hành động cụ thể.
2. Phê duyệt và Điều phối (Application Execution): Ứng dụng tạm dừng quy trình, lưu đề xuất vào hàng đợi chờ duyệt (review queue) và đợi nhân viên hỗ trợ xác nhận trước khi cập nhật trạng thái ticket hoặc gửi tin nhắn cho khách hàng.

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

---

Cấu hình Node.js SDK: Base URL và Xác thực

Gói npm openai chính thức cho phép bạn trỏ request tới bất kỳ endpoint nào tương thích bằng cách chỉnh sửa thuộc tính baseURL. Bạn có thể tham khảo danh sách mô hình hiện có trên OneMux model catalog để lựa chọn mô hình completion phù hợp.

Trước tiên, hãy cài đặt gói chính thức:

npm install openai

Để kết nối tới OneMux, hãy cấu hình instance client với API key của OneMux và base 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',
});

Xác minh tính hợp lệ của xác thực

Khi định tuyến qua gateway, các kịch bản lỗi xác thực có đôi chút khác biệt. Nếu API key bị thiếu, không hợp lệ hoặc tài khoản không đủ số dư trên nền tảng, client sẽ nhận về AuthenticationError (HTTP 401). Trước khi chạy các tác vụ phân loại trên môi trường production, hãy kiểm tra kỹ thông tin xác thực của bạn bằng cách tham khảo OneMux quickstart guide.

---

Triển khai Streaming để soạn thảo phân loại theo thời gian thực

Nhân viên hỗ trợ sẽ làm việc hiệu quả hơn khi nhìn thấy nội dung bản thảo phân loại xuất hiện tuần tự thay vì phải chờ toàn bộ payload hoàn tất. Khi gọi chat.completions.create với tùy chọn stream: true, SDK sẽ trả về một luồng async iterable cung cấp các Server-Sent Events (SSE).

Đoạn mã sau triển khai stream phản hồi dự thảo ra standard output (hoặc dashboard nội bộ của nhân viên) đồng thời ghi nhận các tool calls có cấu trúc phục vụ phân loại ticket:

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,
  };
}

---

Cổng phê duyệt của con người (Human Approval Gate)

Việc để tool calls tự động thực thi có thể dẫn đến những lệnh hoàn tiền không được kiểm chứng hoặc nâng cấp mức độ ưu tiên sai lệch. Ứng dụng phải lưu trữ TriageProposal đã tạo ở trạng thái trung gian—chẳng hạn như một bản ghi cơ sở dữ liệu có trạng thái PENDING_APPROVAL—thay vì thực thi hành động ngay lập tức.

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);
}

Sự phân tách này đảm bảo rằng ngay cả khi mô hình phân loại nhầm một câu hỏi thông thường thành khẩn cấp hoặc đề xuất mức tín dụng không thỏa đáng, nhân viên vận hành vẫn kịp thời ngăn chặn hành động đó trước khi nó được thực thi.

---

Chẩn đoán lỗi: Phân biệt lỗi Client, Gateway và Upstream

Khi sử dụng gateway tương thích OpenAI như OneMux, sự cố có thể bắt nguồn từ ba vị trí: mã ứng dụng cục bộ, proxy gateway hoặc nhà cung cấp mô hình downstream. Việc kiểm tra instance APIError chuẩn từ openai SDK sẽ giúp cô lập nguyên nhân gốc rễ:

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);
  }
}

Phân tích các mã trạng thái phổ biến

---

Giới hạn và các tham số chưa kiểm thử

Mặc dù OneMux cung cấp khả năng tương thích thay thế trực tiếp (drop-in) cho các endpoint chat completion tiêu chuẩn của OpenAI (/v1/chat/completions), bạn cần lưu ý một số giới hạn sau:

1. Các endpoint Beta nâng cao: Những endpoint nằm ngoài phạm vi chat, embeddings và completions cốt lõi—chẳng hạn như môi trường sandbox chuyên dụng hoặc các runtime primitives của Assistants API được nêu trong tài liệu OpenAI—đòi hỏi sự hỗ trợ tường minh từ gateway. Hãy kiểm tra tính khả dụng của endpoint trong tài liệu gateway trước khi triển khai.
2. Chuyển tiếp Custom Header: Các header tùy chỉnh về tổ chức hoặc dự án (OpenAI-Organization, OpenAI-Project) có thể bị bỏ qua hoặc được ánh xạ khác đi qua các lớp proxy. Hãy đảm bảo auth token của bạn được truyền qua header chuẩn Bearer authorization.
3. Quản lý trạng thái (State Management): Nếu bạn dự định chuyển đổi từ OpenAI Assistants API sang một vòng lặp agent do ứng dụng tự quản lý, ứng dụng Node.js của bạn sẽ chịu trách nhiệm lưu trữ lịch sử phiên và duy trì trạng thái.

---

Kết luận

Việc chuyển đổi một ứng dụng Node.js OpenAI SDK sẵn có sang gateway tương thích OpenAI diễn ra rất liền mạch: chỉ cần cập nhật baseURL, cung cấp API key tương ứng của gateway và điều chỉnh cơ chế ghi log lỗi để theo dõi các mã trạng thái đặc thù của gateway. Bằng cách tách biệt đề xuất của mô hình khỏi các tác động phụ thực tế thông qua một cổng phê duyệt, pipeline phân loại hỗ trợ khách hàng của bạn vừa duy trì được tốc độ vận hành cao vừa ngăn ngừa được các hành động ngoài ý muốn.

---

Nguồn tham khảo

• Hướng dẫn OpenAI Agents: https://developers.openai.com/api/docs/guides/agents
• Tài liệu dành cho nhà phát triển OneMux: https://onemux.net/docs