Incident संकेत खोए बिना Node.js OpenAI SDK ऐप माइग्रेट करें

माइग्रेशन की सीमा से शुरुआत करें

Node.js ऐप माइग्रेट करते समय SDK, endpoint, model और streaming कोड—सब कुछ एक साथ न बदलें। पहले नए कॉन्फ़िगरेशन के साथ एक non-streaming अनुरोध करें, फिर streaming जाँचें और अंत में विफलताओं को संभालने के तरीके की तुलना करें। इससे पता लगाने में मदद मिलती है कि समस्या क्रेडेंशियल, routing, अनुरोध की संगतता या stream को पढ़ने से जुड़ी है।

OpenAI की library गाइड में server-side JavaScript के लिए आधिकारिक JavaScript/TypeScript SDK की सिफ़ारिश की गई है और दिखाया गया है कि यह environment से API key पढ़ता है। इसमें Responses API के ज़रिए एक बुनियादी अनुरोध का उदाहरण भी है। SDK के मौजूदा विकल्पों और विवरण के लिए OpenAI की SDK और CLI गाइड और openai-node repository देखें।

ज़रूरी चीज़ें और कॉन्फ़िगरेशन

अपने इंस्टॉल किए गए SDK वर्शन के लिए समर्थित Node.js runtime का उपयोग करें, पैकेज इंस्टॉल करें और deployment environment के ज़रिए क्रेडेंशियल उपलब्ध कराएँ:

npm install openai
export OPENAI_API_KEY="your_api_key_here"

Environment variable वाली कमांड स्थानीय Unix-जैसे shell के लिए है। Production में अपने host या container environment में इसके समकक्ष secret सेट करें। इसे source control में commit न करें, logs में प्रिंट न करें और frontend code में उजागर न करें।

मानक OpenAI API के लिए, client को इसके default endpoint के साथ initialize करें:

import OpenAI from "openai";

const client = new OpenAI({
  // The SDK reads OPENAI_API_KEY from the environment by default.
  timeout: 30_000,
  maxRetries: 2,
});

ऊपर दिए गए timeout और retry मान ऐप्लिकेशन के उदाहरणात्मक विकल्प हैं, सार्वभौमिक सिफ़ारिशें नहीं। किसी खास विकल्प या default पर निर्भर होने से पहले इंस्टॉल किए गए SDK वर्शन का दस्तावेज़ देखें।

किसी दूसरे endpoint पर माइग्रेट कर रहे हों, तो baseURL तभी कॉन्फ़िगर करें जब आपने उस provider के दस्तावेज़ में दिए API path और समर्थित request fields की पुष्टि कर ली हो। संगतता कुछ शर्तों पर निर्भर करती है: OpenAI-संगत URL होने भर से यह साबित नहीं होता कि हर model, parameter, streaming event या error response एक-जैसा व्यवहार करेगा। उस endpoint के लिए उपयुक्त key रखें और production में भेजे जाने वाले ठीक उसी अनुरोध के प्रारूप को जाँचें।

const client = new OpenAI({
  apiKey: process.env.OPENAI_API_KEY,
  baseURL: process.env.OPENAI_BASE_URL,
});

यह कॉन्फ़िगरेशन का उदाहरणात्मक तरीका है। अपने SDK वर्शन और destination के दस्तावेज़ में baseURL के समर्थन और endpoint-विशिष्ट ज़रूरतों की पुष्टि करें। सिर्फ़ विफल अनुरोध को छिपाने के लिए कस्टम URL सेट न करें; पहले पता लगाएँ कि ऐप्लिकेशन को किस host तक पहुँचना चाहिए।

स्ट्रीमिंग से पहले Responses API अनुरोध जाँचें

एक न्यूनतम अनुरोध से endpoint और प्रमाणीकरण की समस्याओं को stream संभालने की समस्याओं से अलग करना आसान होता है:

const response = await client.responses.create({
  model: process.env.OPENAI_MODEL,
  input: "Reply with the word ready.",
});

console.log(response.output_text);

ऐसा model चुनें जो खाते और endpoint के लिए उपलब्ध हो। उदाहरण में environment variable का उपयोग किया गया है, ताकि model का चयन स्पष्ट रहे और चुपचाप मानकर न चला जाए। अगर यह अनुरोध विफल हो, तो stream logic जोड़ने से पहले status और response का निदान करें।

आउटपुट स्ट्रीम करें और पूरा होने की स्थिति दर्ज करें

Responses API के लिए stream का अनुरोध करें और उसके events को पढ़ें। नीचे दिया गया तरीका उदाहरणात्मक है; इंस्टॉल किए गए SDK वर्शन के अनुसार event types की पुष्टि करें:

try {
  const stream = await client.responses.create({
    model: process.env.OPENAI_MODEL,
    input: "Summarize the incident in one sentence.",
    stream: true,
  });

  let completed = false;

  for await (const event of stream) {
    if (event.type === "response.output_text.delta") {
      process.stdout.write(event.delta);
    } else if (event.type === "response.completed") {
      completed = true;
    } else if (event.type === "response.failed") {
      throw new Error("Response stream reported a failure");
    }
  }

  if (!completed) {
    throw new Error("Stream ended without a completion event");
  }
} catch (error) {
  console.error("OpenAI request failed", {
    name: error?.name,
    status: error?.status,
    requestId: error?.request_id,
    message: error?.message,
  });
  throw error;
}

उपयोगकर्ता को पहले से दिखाए गए टेक्स्ट को इस बात का प्रमाण न मानें कि अनुरोध सफल हुआ। Stream आंशिक आउटपुट देने के बाद विफल हो सकती है या अप्रत्याशित रूप से समाप्त हो सकती है। आपके ऐप्लिकेशन को तय करना चाहिए कि आंशिक टेक्स्ट रखना है, फिर से प्रयास करना है या response को अधूरा चिह्नित करना है। अगर UI इसे स्पष्ट रूप से नहीं संभालता, तो आंशिक रूप से दिखाए गए generation को फिर से चलाने पर उपयोगकर्ता को वही सामग्री दोबारा दिख सकती है।

निगरानी योग्य संकेतों से विफलताओं का निदान करें

हर अनुरोध के लिए कुछ निश्चित फ़ील्ड दर्ज करें: timestamp, endpoint host (क्रेडेंशियल के बिना), model identifier, बीता हुआ समय, उपलब्ध होने पर HTTP status, SDK error class/name, उपलब्ध होने पर request ID और stream पूरी हुई या नहीं। जहाँ prompt और response text में संवेदनशील जानकारी हो सकती है, उन्हें redact करें।

ये निदान शुरू करने के संकेत हैं, निश्चित कारण नहीं। केवल status code से यह पता नहीं चलता कि ज़िम्मेदार system कौन-सा है। उपलब्ध होने पर application और provider logs के timestamps और request IDs की तुलना करें, और non-idempotent application workflows को बिना सोचे-समझे retry न करें।

माइग्रेशन चेकलिस्ट

1. SDK वर्शन को pin करके दर्ज करें; Node.js और कॉन्फ़िगरेशन से जुड़ी मौजूदा ज़रूरतें देखें।
2. Destination URL, प्रमाणीकरण का तरीका, model की उपलब्धता और समर्थित request parameters की पुष्टि करें।
3. Production-जैसे runtime से एक non-streaming अनुरोध करें।
4. पूरी हुई stream, बीच में बाधित stream और अस्वीकृत अनुरोध की जाँच करें।
5. पुष्टि करें कि logs में उपयोगी विफलता-संबंधी metadata है, लेकिन क्रेडेंशियल या संवेदनशील सामग्री नहीं।
6. बदलाव को नियंत्रित तरीके से roll out करें और पुराने तरीके से status, latency तथा completion संकेतों की तुलना करें।

माइग्रेशन का अच्छा नतीजा केवल सफल response मिलना नहीं है। ऐप्लिकेशन को पूरा उत्तर और आंशिक आउटपुट अलग-अलग पहचानने में सक्षम होना चाहिए, और अनुरोध विफल होने पर ऑपरेटर को यह बता पाना चाहिए कि आगे कहाँ जाँच करें।