OpenAI SDK для JavaScript (Node.js): полное руководство с примерами

Добро пожаловать в самое полное руководство по использованию официального OpenAI SDK для языка JavaScript в среде Node.js. Эта статья создана специально для образовательного портала PythonLib, чтобы помочь разработчикам любого уровня быстро и эффективно интегрировать возможности искусственного интеллекта от OpenAI в свои веб-приложения, боты и серверные решения.

1. Что это и зачем нужна

OpenAI SDK для JavaScript — это официальная библиотека, предоставляемая компанией OpenAI для взаимодействия с их API из приложений, написанных на JavaScript (Node.js). Она представляет собой удобную обёртку над REST API, которая берёт на себя всю рутинную работу: формирование HTTP-запросов, обработку ответов, управление аутентификацией, повторные попытки при ошибках сети и потоковую передачу данных (streaming). Вместо того чтобы вручную писать fetch-запросы, обрабатывать JSON и управлять токенами, вы получаете интуитивно понятный интерфейс с методами, названия которых говорят сами за себя — chat.completions.create(), embeddings.create(), images.generate() и другие.

Зачем эта библиотека нужна? Во-первых, она радикально ускоряет разработку. Вместо десятков строк кода для одного запроса к ChatGPT, вы пишете 3-5 строк. Во-вторых, SDK автоматически обрабатывает такие сложные вещи, как потоковая передача (streaming) — когда ответ от модели приходит частями, что критически важно для создания чат-интерфейсов с отображением текста "на лету". В-третьих, библиотека поддерживает TypeScript из коробки, предоставляя полную типизацию всех запросов и ответов, что позволяет ловить ошибки на этапе написания кода, а не во время выполнения. Наконец, это официальный инструмент, который обновляется вместе с API, поэтому вы всегда будете иметь доступ к новейшим моделям и функциям, таким как GPT-4o, DALL-E 3, Whisper и TTS.

Эта библиотека идеально подходит для создания чат-ботов, интеллектуальных ассистентов, систем анализа текста, генерации контента, перевода, суммаризации, а также для интеграции с фреймворками вроде Express.js, Next.js, или Telegram Bot API. Если вы пишете на Node.js и хотите добавить в свой проект "мозги" от OpenAI — этот SDK — ваш выбор.

2. Установка

Установка библиотеки производится через стандартный менеджер пакетов npm. Убедитесь, что у вас установлен Node.js версии 18 или выше (рекомендуется 20 LTS).

Точная команда для установки:

npm install openai

Если вы используете yarn:

yarn add openai

После установки, для работы вам потребуется API-ключ от OpenAI. Получить его можно на странице platform.openai.com/api-keys. Ключ необходимо хранить в безопасности, например, в переменной окружения OPENAI_API_KEY.

3. Быстрый старт — минимальный рабочий пример

Давайте напишем простейший скрипт, который задаёт вопрос модели GPT-4o и выводит ответ. Создайте файл quickstart.mjs (используем ES-модули) или quickstart.js (для CommonJS).

// quickstart.mjs — используем ES-модули
import OpenAI from "openai";

const openai = new OpenAI({
  apiKey: process.env["OPENAI_API_KEY"], // ключ из переменной окружения
});

async function main() {
  const completion = await openai.chat.completions.create({
    model: "gpt-4o",
    messages: [
      { role: "system", content: "Ты — полезный ассистент." },
      { role: "user", content: "Напиши краткое приветствие на русском языке." },
    ],
  });

  console.log(completion.choices[0].message.content);
}

main();

Запустите скрипт:

export OPENAI_API_KEY="sk-..." # Linux/macOS
set OPENAI_API_KEY="sk-..."    # Windows CMD
$env:OPENAI_API_KEY="sk-..."   # Windows PowerShell

node quickstart.mjs

В консоли вы увидите что-то вроде: "Привет! Рад помочь вам сегодня."

4. Основные методы/функции/классы

Библиотека построена вокруг главного класса OpenAI, который содержит вложенные пространства имён (namespaces) для разных групп методов: chat, embeddings, images, audio, models, files, fineTuning, moderations и другие. Рассмотрим 8 ключевых методов, которые покроют 90% всех задач.

4.1. openai.chat.completions.create()

Сигнатура:

async create(
  body: ChatCompletionCreateParamsNonStreaming | ChatCompletionCreateParamsStreaming,
  options?: RequestOptions
): Promise<ChatCompletion | Stream<ChatCompletionChunk>>

Что делает: Отправляет запрос к чат-модели (GPT-4o, GPT-4, GPT-3.5-turbo) и получает ответ. Это основной метод для построения диалоговых систем. Поддерживает как обычные запросы, так и потоковую передачу (streaming).

Рабочий пример кода:

import OpenAI from "openai";

const openai = new OpenAI();

async function chatExample() {
  const response = await openai.chat.completions.create({
    model: "gpt-4o",
    messages: [
      { role: "system", content: "Ты — эксперт по JavaScript." },
      { role: "user", content: "Объясни разницу между var, let и const." },
    ],
    temperature: 0.7, // контролирует "креативность" (0-2)
    max_tokens: 300,   // максимальная длина ответа
  });

  console.log("Ответ модели:", response.choices[0].message.content);
  console.log("Использовано токенов:", response.usage.total_tokens);
}

chatExample();

4.2. openai.embeddings.create()

Сигнатура:

async create(
  body: EmbeddingCreateParams,
  options?: RequestOptions
): Promise<CreateEmbeddingResponse>

Что делает: Преобразует текст в векторное представление (эмбеддинг) — массив чисел, который отражает смысл текста. Используется для поиска по смыслу (semantic search), кластеризации, рекомендательных систем.

Рабочий пример кода:

import OpenAI from "openai";

const openai = new OpenAI();

async function embeddingExample() {
  const response = await openai.embeddings.create({
    model: "text-embedding-3-small", // лучшая модель для эмбеддингов
    input: "Искусственный интеллект меняет мир",
  });

  const embedding = response.data[0].embedding;
  console.log("Размерность вектора:", embedding.length); // 1536 для text-embedding-3-small
  console.log("Первые 5 значений:", embedding.slice(0, 5));
}

embeddingExample();

4.3. openai.images.generate()

Сигнатура:

async generate(
  body: ImageGenerateParams,
  options?: RequestOptions
): Promise<ImagesResponse>

Что делает: Генерирует изображение по текстовому описанию (prompt) с помощью модели DALL-E 3 или DALL-E 2. Результат можно получить в виде URL или base64-строки.

Рабочий пример кода:

import OpenAI from "openai";
import fs from "fs";
import https from "https";

const openai = new OpenAI();

async function generateImage() {
  const response = await openai.images.generate({
    model: "dall-e-3",
    prompt: "Кот в космическом скафандре сидит на Марсе, цифровая живопись",
    n: 1,
    size: "1024x1024",
    quality: "hd",
  });

  const imageUrl = response.data[0].url;
  console.log("URL изображения:", imageUrl);

  // Скачиваем изображение
  const filename = "cat_in_space.png";
  const file = fs.createWriteStream(filename);
  https.get(imageUrl, (res) => {
    res.pipe(file);
    file.on("finish", () => console.log(`Изображение сохранено как ${filename}`));
  });
}

generateImage();

4.4. openai.audio.transcriptions.create()

Сигнатура:

async create(
  body: TranscriptionCreateParams,
  options?: RequestOptions
): Promise<Transcription>

Что делает: Транскрибирует аудиофайл в текст с помощью модели Whisper. Поддерживает множество форматов (mp3, wav, m4a, ogg и др.) и языков.

Рабочий пример кода:

import OpenAI from "openai";
import fs from "fs";

const openai = new OpenAI();

async function transcribeAudio() {
  const audioFile = fs.createReadStream("speech.mp3");

  const transcription = await openai.audio.transcriptions.create({
    model: "whisper-1",
    file: audioFile,
    language: "ru", // опционально: указываем язык для точности
  });

  console.log("Распознанный текст:", transcription.text);
}

transcribeAudio();

4.5. openai.audio.speech.create()

Сигнатура:

async create(
  body: SpeechCreateParams,
  options?: RequestOptions
): Promise<Response>

Что делает: Преобразует текст в речь (Text-to-Speech) с помощью модели TTS. Возвращает аудиофайл в формате MP3, Opus, AAC, FLAC или WAV. Доступно 6 голосов: alloy, echo, fable, onyx, nova, shimmer.

Рабочий пример кода:

import OpenAI from "openai";
import fs from "fs";

const openai = new OpenAI();

async function textToSpeech() {
  const mp3Response = await openai.audio.speech.create({
    model: "tts-1",
    voice: "nova",
    input: "Привет! Это сгенерированная речь от OpenAI.",
    speed: 1.0, // скорость речи (0.25 - 4.0)
  });

  // Сохраняем в файл
  const buffer = Buffer.from(await mp3Response.arrayBuffer());
  fs.writeFileSync("speech.mp3", buffer);
  console.log("Аудиофайл сохранён как speech.mp3");
}

textToSpeech();

4.6. openai.moderations.create()

Сигнатура:

async create(
  body: ModerationCreateParams,
  options?: RequestOptions
): Promise<ModerationCreateResponse>

Что делает: Проверяет текст на наличие нежелательного контента (ненависть, насилие, сексуальный контент, самоповреждение и т.д.). Незаменим для модерации пользовательского контента в чатах и комментариях.

Рабочий пример кода:

import OpenAI from "openai";

const openai = new OpenAI();

async function moderateText() {
  const result = await openai.moderations.create({
    model: "omni-moderation-latest", // самая свежая модель модерации
    input: "Я тебя ненавижу и хочу, чтобы ты исчез!",
  });

  const moderation = result.results[0];
  console.log("Флаг нарушений:", moderation.flagged);
  if (moderation.flagged) {
    console.log("Категории:", moderation.categories);
    console.log("Оценки:", moderation.category_scores);
  }
}

moderateText();

4.7. openai.models.list()

Сигнатура:

async list(
  query?: ModelListParams,
  options?: RequestOptions
): Promise<ModelList>

Что делает: Возвращает список всех доступных моделей для вашего аккаунта. Полезно для проверки доступности новых моделей или для динамического выбора модели в приложении.

Рабочий пример кода:

import OpenAI from "openai";

const openai = new OpenAI();

async function listModels() {
  const models = await openai.models.list();

  // Выводим только GPT модели
  const gptModels = models.data.filter(m => m.id.includes("gpt"));
  console.log("Доступные GPT модели:");
  gptModels.forEach(m => console.log(`  - ${m.id} (создана: ${m.created})`));
}

listModels();

4.8. openai.files.create() и openai.files.content()

Сигнатура:

async create(
  body: FileCreateParams,
  options?: RequestOptions
): Promise<FileObject>

async content(
  fileId: string,
  options?: RequestOptions
): Promise<Response>

Что делает: Загружает файл на сервер OpenAI (например, для fine-tuning или для использования в Assistants API) и позволяет получить его содержимое. Файлы могут быть в форматах JSONL, JSON, TXT, PDF, DOCX и других.

Рабочий пример кода:

import OpenAI from "openai";
import fs from "fs";

const openai = new OpenAI();

async function uploadAndRetrieveFile() {
  // Загружаем файл
  const uploadedFile = await openai.files.create({
    file: fs.createReadStream("training_data.jsonl"),
    purpose: "fine-tune", // или "assistants", "batch"
  });
  console.log("Файл загружен, ID:", uploadedFile