Node.js OpenAI SDK ऐप्लिकेशन्स का माइग्रेशन: Base URL, स्ट्रीमिंग, और स्ट्रक्चर्ड आउटपुट्स

Introduction

आधिकारिक openai SDK का उपयोग करने वाले किसी मौजूदा Node.js एप्लिकेशन को माइग्रेट करने के लिए आपके बिज़नेस लॉजिक को दोबारा लिखने की आवश्यकता नहीं होती है। चूँकि कई यूनिफ़ाइड मॉडल प्रोवाइडर्स OpenAI REST स्पेसिफिकेशन्स का सख्ती से पालन करते हैं, इसलिए किसी मौजूदा एप्लिकेशन को OneMux जैसे OpenAI-कंपैटिबल रूटिंग लेयर के माध्यम से चलाने के लिए केवल आपके क्लाइंट इनिशियलाइज़ेशन पैरामीटर्स को अपडेट करना पड़ता है।

हालाँकि, प्रोडक्शन पाइपलाइन्स अक्सर एडवांस्ड फीचर्स पर निर्भर करती हैं: डेटा एक्सट्रैक्शन के लिए स्ट्रिक्ट स्कीमा अनुपालन, टोकन-दर-टोकन स्ट्रीमिंग, और मजबूत एरर रिकवरी। यह गाइड बताती है कि Node.js OpenAI SDK को कैसे रीकॉन्फ़िगर करें, स्ट्रक्चर्ड JSON schema एक्सट्रैक्शन कैसे निष्पादित करें, स्ट्रीमिंग रिस्पॉन्स को विश्वसनीयता से कैसे संभालें, और एक्ज़ीक्यूशन एरर्स का डायग्नोसिस कैसे करें।

---

Step 1: Base URL and Authentication Configuration

आधिकारिक OpenAI Node.js SDK (openai v4+) सीधे OpenAI क्लास कन्स्ट्रक्टर के भीतर कॉन्फ़िगरेशन ओवरराइड्स स्वीकार करता है। अपने ट्रांसपोर्ट लेयर को OpenAI-कंपैटिबल एंडपॉइंट पर माइग्रेट करने के लिए, baseURL प्रॉपर्टी कॉन्फ़िगर करें और अपनी API key सेट करें।

SDK Client Initialization

import OpenAI from "openai";

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

Migration Prerequisites

1. Environment Variables: सुनिश्चित करें कि आप अपने .env कॉन्फ़िगरेशन में प्रोवाइडर कीज़ को अलग रखते हैं (उदाहरण के लिए, ONEMUX_API_KEY बनाम OPENAI_API_KEY)।
2. Path Suffix: OpenAI का SDK अपने आप baseURL में /chat/completions जैसे रूट पाथ जोड़ देता है। हमेशा सुनिश्चित करें कि आपके baseURL में /v1 सफिक्स शामिल हो (जैसे, https://api.onemux.net/v1), जब तक कि आपका गेटवे रूट रूटिंग को खुद हैंडल न करता हो।
3. SDK Version: पुष्टि करें कि आप openai वर्ज़न ^4.0.0 या उससे उच्चतर चला रहे हैं, क्योंकि पुराने v3 वर्ज़न एक अलग कॉन्फ़िगरेशन स्ट्रक्चर (Configuration क्लास) का उपयोग करते थे।

सपोर्टेड रूटिंग नियमों की समीक्षा करने और API क्रेडेंशियल्स के साथ शुरुआत करने के लिए, OneMux Quickstart पर जाएँ।

---

Step 2: Structured Extraction with Strict JSON Schema

स्ट्रक्चर्ड आउटपुट्स मॉडल्स को दिए गए JSON Schema के बिल्कुल अनुरूप आउटपुट लौटाने के लिए बाध्य करते हैं। स्ट्रक्चर्ड आउटपुट्स पर OpenAI के डॉक्यूमेंटेशन के अनुसार, "strict": true सेट करने पर निम्नलिखित आवश्यक है:

• सभी ऑब्जेक्ट फ़ील्ड्स required ऐरे में सूचीबद्ध होने चाहिए।
• सभी ऑब्जेक्ट स्कीमा पर additionalProperties: false स्पष्ट रूप से परिभाषित होना चाहिए।
• वैकल्पिक (optional) फ़ील्ड्स को null के साथ यूनियन टाइप्स के रूप में मॉडल किया जाना चाहिए (उदा. ["string", "null"])।

Standard Structured Completion Implementation

import OpenAI from "openai";

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

// Define strict JSON Schema for invoice extraction
const invoiceExtractionSchema = {
  type: "object",
  properties: {
    vendorName: { type: "string" },
    invoiceId: { type: "string" },
    totalAmount: { type: "number" },
    currency: { type: "string" },
    items: {
      type: "array",
      items: {
        type: "object",
        properties: {
          description: { type: "string" },
          quantity: { type: "number" },
          unitPrice: { type: "number" },
        },
        required: ["description", "quantity", "unitPrice"],
        additionalProperties: false,
      },
    },
  },
  required: ["vendorName", "invoiceId", "totalAmount", "currency", "items"],
  additionalProperties: false,
} as const;

async function extractInvoice(rawDocumentText: string) {
  const response = await client.chat.completions.create({
    model: "gpt-4o",
    messages: [
      {
        role: "system",
        content: "Extract normalized invoice records from the provided unstructured input.",
      },
      {
        role: "user",
        content: rawDocumentText,
      },
    ],
    response_format: {
      type: "json_schema",
      json_schema: {
        name: "invoice_extraction",
        strict: true,
        schema: invoiceExtractionSchema,
      },
    },
  });

  const choice = response.choices[0];

  // Check for safety or policy refusals
  if (choice.message.refusal) {
    throw new Error(`Model refused extraction: ${choice.message.refusal}`);
  }

  const rawJson = choice.message.content;
  if (!rawJson) {
    throw new Error("Received empty response payload");
  }

  return JSON.parse(rawJson);
}

डाउनस्ट्रीम गेटवे के साथ कम्पैटिबिलिटी इस बात पर निर्भर करती है कि अंतर्निहित प्रोवाइडर एंडपॉइंट strict: true के साथ json_schema मोड को सपोर्ट करता है या नहीं। विभिन्न प्लेटफ़ॉर्म्स पर मॉडल की क्षमताओं के विवरण के लिए, OneMux Models catalog देखें।

---

Step 3: Handling Streaming with Structured Outputs

जब response_format के साथ stream: true सक्षम किया जाता है, तो मॉडल JSON पेलोड के आंशिक स्ट्रिंग फ़्रैग्मेंट्स को स्ट्रीम करता है। सामान्य टेक्स्ट चैट के विपरीत, अलग-अलग चंक्स को JSON.parse() से पार्स नहीं किया जा सकता क्योंकि वे अपूर्ण JSON टोकन्स का प्रतिनिधित्व करते हैं।

Accumulating Streamed JSON Chunks

स्ट्रक्चर्ड आउटपुट्स को सही ढंग से स्ट्रीम करने के लिए, स्ट्रीम पूरा होने तक डेल्टा फ़्रैग्मेंट्स को इकट्ठा करें, या इनकमिंग चंक्स को एक इंक्रीमेंटल JSON स्ट्रीम पार्सर के माध्यम से पाइप करें।

async function streamInvoiceExtraction(rawDocumentText: string) {
  const stream = await client.chat.completions.create({
    model: "gpt-4o",
    stream: true,
    messages: [
      {
        role: "system",
        content: "Extract normalized invoice records from the provided text.",
      },
      {
        role: "user",
        content: rawDocumentText,
      },
    ],
    response_format: {
      type: "json_schema",
      json_schema: {
        name: "invoice_extraction",
        strict: true,
        schema: invoiceExtractionSchema,
      },
    },
  });

  let accumulatedJson = "";
  let refusalReason: string | null = null;

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

    if (delta?.refusal) {
      refusalReason = (refusalReason || "") + delta.refusal;
    }

    if (delta?.content) {
      accumulatedJson += delta.content;
      // Emit partial events or log progress if building a reactive UI
    }
  }

  if (refusalReason) {
    throw new Error(`Extraction was refused during stream: ${refusalReason}`);
  }

  try {
    return JSON.parse(accumulatedJson);
  } catch (err) {
    throw new Error(`Failed to parse streamed JSON payload: ${accumulatedJson}`);
  }
}

यदि आपकी पाइपलाइन केवल यूज़र इंटरफ़ेस में टाइम-टू-फर्स्ट-बाइट (TTFB) को कम करने के लिए स्ट्रीमिंग का उपयोग करती है, तो सत्यापित करें कि डाउनस्ट्रीम एंडपॉइंट आपके नेटवर्क प्रॉक्सी के माध्यम से निरंतर Server-Sent Events (SSE) का समर्थन करता है।

---

Step 4: Error Diagnosis and Troubleshooting

SDK कॉल्स को कस्टम baseURL पर माइग्रेट करते समय, एरर डायग्नोसिस को नेटवर्क प्रॉक्सी विफलताओं, स्कीमा गलत कॉन्फ़िगरेशन, रेट लिमिट्स और मॉडल रिफ़्यूज़ल्स के बीच अंतर करना चाहिए।

Common Errors and Resolution Strategies

Structured Error Handling Wrapper

import OpenAI from "openai";

async function safeExtractWrapper(fn: () => Promise<any>) {
  try {
    return await fn();
  } catch (error: any) {
    if (error instanceof OpenAI.APIError) {
      console.error(`OpenAI API Error: status=${error.status}, type=${error.type}`);
      console.error(`Message: ${error.message}`);

      if (error.status === 400) {
        console.error("Verify that your schema complies strictly with JSON Schema constraints.");
      } else if (error.status === 401) {
        console.error("Authentication failed: Check your bearer token and proxy baseURL.");
      } else if (error.status === 429) {
        console.warn("Rate limit reached. Queue request for delayed retry.");
      }
    } else {
      console.error("Unexpected application error:", error);
    }
    throw error;
  }
}

---

Step 5: Consolidating Providers via OneMux

OneMux के माध्यम से OpenAI SDK अनुरोधों को रूट करने से थर्ड-पार्टी लाइब्रेरीज़ या कस्टम प्रोटोकॉल एडेप्टर की आवश्यकता के बिना मल्टी-मॉडल संचालन सरल हो जाता है।

• यूनिफ़ाइड एंडपॉइंट: मानक OpenAI SDK सिमेंटिक्स का उपयोग करके विभिन्न मॉडल्स में रूट करते हुए एकल क्लाइंट इंटरफ़ेस बनाए रखें।
• खर्च प्रबंधन और विजिबिलिटी: कई प्रोवाइडर्स के इनवॉइस प्रबंधित किए बिना बिलिंग को केंद्रीकृत करें, प्रति-मॉडल उपयोग की समीक्षा करें, और खर्च के नियम निर्धारित करें।
• लचीला Pay-as-You-Go: लचीले क्रेडिट टॉप-अप के माध्यम से अपने खाते को फंड करें, जिससे सेवाओं में अप्रत्याशित रुकावट से बचा जा सके।

वर्तमान उपयोग दरों को देखने और मॉडल्स में रूटिंग विकल्पों की तुलना करने के लिए, OneMux Pricing Guide देखें और OneMux Documentation में तकनीकी विवरण पढ़ें।

---

Sources

• OpenAI Developer Documentation & Changelog
• OpenAI Structured Outputs Guide