【TypeScript】OpenAI API入門｜Chat Completions・ストリーミング・Function Calling・画像認識・構造化出力まで実装する方法

mkdir openai-ts-sample && cd openai-ts-sample
npm init -y
npm install typescript tsx @types/node --save-dev
npm install openai
npx tsc --init

{
  "compilerOptions": {
    "target": "ES2022",
    "module": "Node16",
    "moduleResolution": "Node16",
    "outDir": "./dist",
    "strict": true,
    "esModuleInterop": true
  },
  "include": ["src/**/*"]
}

OPENAI_API_KEY=sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

.env
node_modules/
dist/

node --env-file=.env -r tsx/esm src/index.ts

import OpenAI from "openai";

const client = new OpenAI();
// OPENAI_API_KEY 環境変数から自動でAPIキーを読み込む

const response = await client.chat.completions.create({
  model: "gpt-4o",
  messages: [
    { role: "user", content: "TypeScriptの型推論の仕組みを200字で説明してください。" }
  ],
});

// 生成されたテキストを取り出す
const text = response.choices[0].message.content;
console.log(text);

// トークン使用量の確認
console.log(`入力: ${response.usage?.prompt_tokens} / 出力: ${response.usage?.completion_tokens} トークン`);

import type { ChatCompletion } from "openai/resources";

// ChatCompletion の主なフィールド
interface ChatCompletionShape {
  id: string;                  // レスポンスID
  model: string;               // 使用したモデル
  choices: Array<{
    index: number;
    message: {
      role: "assistant";
      content: string | null;  // テキスト応答
      tool_calls?: ToolCall[];  // Function Calling 使用時
    };
    finish_reason:
      | "stop"         // 正常終了
      | "length"       // max_tokens に到達
      | "tool_calls"   // Function Calling 要求
      | "content_filter"; // コンテンツフィルター
  }>;
  usage?: {
    prompt_tokens: number;      // 入力トークン
    completion_tokens: number;  // 出力トークン
    total_tokens: number;       // 合計（= 課金対象）
  };
}

import OpenAI from "openai";
import type { ChatCompletionMessageParam } from "openai/resources";

const client = new OpenAI();

// 会話履歴を配列で管理
const history: ChatCompletionMessageParam[] = [
  {
    role: "system",
    content: `あなたはTypeScriptの専門家です。
以下のルールを守ってください：
- 回答は必ず日本語
- コード例はTypeScriptで記述し、型定義を省略しない
- 初心者にもわかりやすく説明する`
  },
];

async function chat(userMessage: string): Promise<string> {
  // ユーザーメッセージを履歴に追加
  history.push({ role: "user", content: userMessage });

  const response = await client.chat.completions.create({
    model: "gpt-4o",
    messages: history,   // 会話履歴を毎回すべて渡す
    temperature: 0.7,
  });

  const assistantText = response.choices[0].message.content ?? "";

  // アシスタントの返答も履歴に追加（次の質問で文脈が使える）
  history.push({ role: "assistant", content: assistantText });

  return assistantText;
}

// 会話例
console.log(await chat("ジェネリクスを教えてください。"));
console.log(await chat("さっき出てきた<T>はどういう意味ですか？"));  // 文脈を参照
console.log(await chat("実務でよく使うパターンを3つ挙げてください。"));

import OpenAI from "openai";

const client = new OpenAI();

// stream: true でストリーミングを有効化
const stream = await client.chat.completions.create({
  model: "gpt-4o",
  messages: [
    { role: "user", content: "TypeScriptのasync/awaitのベストプラクティスを解説してください。" }
  ],
  stream: true,
});

// for await でチャンクを逐次処理
for await (const chunk of stream) {
  // 各チャンクのテキスト差分を取得
  const delta = chunk.choices[0]?.delta?.content;
  if (delta) {
    process.stdout.write(delta);  // 改行なしで逐次表示
  }

  // finish_reason が "stop" になったら完了
  if (chunk.choices[0]?.finish_reason === "stop") {
    console.log("

--- 生成完了 ---");
  }
}

import OpenAI from "openai";

const client = new OpenAI();

const stream = await client.chat.completions.create({
  model: "gpt-4o",
  messages: [{ role: "user", content: "短い詩を書いてください。" }],
  stream: true,
  stream_options: { include_usage: true },  // openai SDK v6以降で利用可能
});

for await (const chunk of stream) {
  const delta = chunk.choices[0]?.delta?.content;
  if (delta) process.stdout.write(delta);

  // 最終チャンクに usage が含まれる
  if (chunk.usage) {
    console.log(`

入力: ${chunk.usage.prompt_tokens} / 出力: ${chunk.usage.completion_tokens} トークン`);
  }
}

import OpenAI from "openai";
import type {
  ChatCompletionTool,
  ChatCompletionMessageParam,
  ChatCompletionToolMessageParam,
} from "openai/resources";

const client = new OpenAI();

// ── ツールの定義 ──────────────────────────────────
const tools: ChatCompletionTool[] = [
  {
    type: "function",
    function: {
      name: "get_weather",
      description: "指定した都市の現在の天気を取得します",
      parameters: {
        type: "object",
        properties: {
          city: {
            type: "string",
            description: "都市名（例: 東京、大阪、札幌）",
          },
          unit: {
            type: "string",
            enum: ["celsius", "fahrenheit"],
            description: "温度の単位",
          },
        },
        required: ["city"],
      },
    },
  },
  {
    type: "function",
    function: {
      name: "search_articles",
      description: "ブログ記事をキーワードで検索します",
      parameters: {
        type: "object",
        properties: {
          keyword: {
            type: "string",
            description: "検索キーワード",
          },
          limit: {
            type: "number",
            description: "取得件数（デフォルト: 5）",
          },
        },
        required: ["keyword"],
      },
    },
  },
];

// ── ツールの実装（実際の処理） ───────────────────────
function executeFunction(name: string, args: Record<string, unknown>): string {
  switch (name) {
    case "get_weather": {
      // 実際はここで天気APIを呼び出す
      const city = args.city as string;
      return JSON.stringify({ city, temp: 22, condition: "晴れ", humidity: 60 });
    }
    case "search_articles": {
      // 実際はここでDBやElasticsearchを検索する
      const keyword = args.keyword as string;
      return JSON.stringify([
        { id: 1, title: `${keyword}の基礎`, url: "/article/1" },
        { id: 2, title: `${keyword}実践ガイド`, url: "/article/2" },
      ]);
    }
    default:
      return JSON.stringify({ error: "未実装のツールです" });
  }
}

// ── Function Calling ループ ───────────────────────
async function runWithTools(userMessage: string): Promise<string> {
  const messages: ChatCompletionMessageParam[] = [
    { role: "user", content: userMessage },
  ];

  // モデルが "stop" を返すまでループ
  while (true) {
    const response = await client.chat.completions.create({
      model: "gpt-4o",
      messages,
      tools,
      tool_choice: "auto",  // "auto": 必要なときだけ呼び出す
    });

    const choice = response.choices[0];

    // ツール呼び出しなし → テキスト応答を返す
    if (choice.finish_reason === "stop") {
      return choice.message.content ?? "";
    }

    // ツール呼び出し要求
    if (choice.finish_reason === "tool_calls") {
      // アシスタントのメッセージ（ツール呼び出し指示）を履歴に追加
      messages.push(choice.message);

      // 各ツールを実行して結果を返す
      const toolResults: ChatCompletionToolMessageParam[] = (
        choice.message.tool_calls ?? []
      ).map((toolCall) => {
        const args = JSON.parse(toolCall.function.arguments) as Record<string, unknown>;
        const result = executeFunction(toolCall.function.name, args);

        console.log(`[ツール実行] ${toolCall.function.name}(${toolCall.function.arguments})`);
        console.log(`[結果] ${result}`);

        return {
          role: "tool" as const,
          tool_call_id: toolCall.id,
          content: result,
        };
      });

      messages.push(...toolResults);
    }
  }
}

// 使用例
const answer = await runWithTools(
  "東京と大阪の天気を調べて、TypeScriptの記事も検索してください。"
);
console.log("
最終回答:", answer);

import OpenAI from "openai";

const client = new OpenAI();

const response = await client.chat.completions.create({
  model: "gpt-4o",
  messages: [
    {
      role: "user",
      content: [
        { type: "text", text: "この画像に写っているコードの問題点を指摘してください。" },
        {
          type: "image_url",
          image_url: {
            url: "https://example.com/code-screenshot.png",
            detail: "high",  // "low" | "high" | "auto"（default）
          },
        },
      ],
    },
  ],
});

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

import OpenAI from "openai";
import * as fs from "fs";
import * as path from "path";

const client = new OpenAI();

// サポートする画像フォーマット: JPEG, PNG, GIF, WebP
function imageToBase64(filePath: string): { base64: string; mimeType: string } {
  const ext = path.extname(filePath).toLowerCase();
  const mimeMap: Record<string, string> = {
    ".jpg": "image/jpeg",
    ".jpeg": "image/jpeg",
    ".png": "image/png",
    ".gif": "image/gif",
    ".webp": "image/webp",
  };
  const mimeType = mimeMap[ext] ?? "image/jpeg";
  const base64 = fs.readFileSync(filePath).toString("base64");
  return { base64, mimeType };
}

const { base64, mimeType } = imageToBase64("./screenshot.png");

const response = await client.chat.completions.create({
  model: "gpt-4o",
  messages: [
    {
      role: "user",
      content: [
        { type: "text", text: "このスクリーンショットのエラーを日本語で説明してください。" },
        {
          type: "image_url",
          image_url: {
            url: `data:${mimeType};base64,${base64}`,
          },
        },
      ],
    },
  ],
  max_tokens: 1024,
});

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

import OpenAI from "openai";

const client = new OpenAI();

const response = await client.chat.completions.create({
  model: "gpt-4o",
  messages: [
    {
      role: "system",
      content: "ユーザーの入力を解析し、必ずJSONで返してください。",
    },
    {
      role: "user",
      content: "山田太郎、30歳、エンジニアの情報をJSONにしてください。",
    },
  ],
  response_format: { type: "json_object" },  // JSON modeを有効化
});

// まだ any 型なので手動でパースが必要
const data = JSON.parse(response.choices[0].message.content ?? "{}");
console.log(data);

npm install zod

import OpenAI from "openai";
import { zodResponseFormat } from "openai/helpers/zod";
import { z } from "zod";

const client = new OpenAI();

// ── 出力スキーマを Zod で定義 ──────────────────────
const ArticleSchema = z.object({
  title: z.string().describe("記事タイトル"),
  summary: z.string().describe("100字程度の要約"),
  tags: z.array(z.string()).describe("関連タグ（3〜5件）"),
  difficulty: z
    .enum(["beginner", "intermediate", "advanced"])
    .describe("難易度"),
  estimatedReadingMinutes: z
    .number()
    .describe("想定読了時間（分）"),
});

// Zod スキーマから TypeScript 型を生成
type Article = z.infer<typeof ArticleSchema>;

// ── 構造化出力で記事メタデータを生成 ───────────────
const response = await client.beta.chat.completions.parse({
  model: "gpt-4o",
  messages: [
    {
      role: "user",
      content:
        "TypeScriptのジェネリクスについての記事メタデータを生成してください。",
    },
  ],
  // zodResponseFormat でスキーマを指定（strict: true が自動適用される）
  response_format: zodResponseFormat(ArticleSchema, "article"),
});

// parsed は Article 型（型安全）
const article: Article = response.choices[0].message.parsed!;

console.log("タイトル:", article.title);
console.log("要約:", article.summary);
console.log("タグ:", article.tags.join(", "));
console.log("難易度:", article.difficulty);
console.log("読了時間:", article.estimatedReadingMinutes, "分");

import OpenAI from "openai";

// maxRetries と timeout を SDK 初期化時に一括設定できる
const client = new OpenAI({
  maxRetries: 3,       // 自動リトライ回数（デフォルト2）
  timeout: 30_000,     // 30秒でタイムアウト
});

async function safeCompletion(message: string): Promise<string | null> {
  try {
    const response = await client.chat.completions.create({
      model: "gpt-4o",
      messages: [{ role: "user", content: message }],
    });
    return response.choices[0].message.content;

  } catch (error) {
    // OpenAI SDK のエラーは APIError のサブクラスに分類される
    if (error instanceof OpenAI.AuthenticationError) {
      console.error("APIキーが無効です。OPENAI_API_KEY を確認してください。");
      throw error;  // 再試行しても意味がないので再スロー
    }

    if (error instanceof OpenAI.RateLimitError) {
      // retry-after ヘッダーがあれば参照、なければ60秒待つ
      const retryAfter = error.headers?.["retry-after"];
      const wait = retryAfter ? parseInt(String(retryAfter), 10) * 1000 : 60_000;
      console.warn(`レート制限です。${wait / 1000}秒後に手動リトライしてください。`);
      return null;
    }

    if (error instanceof OpenAI.InternalServerError) {
      console.warn(`OpenAIサーバーエラー (${error.status})。しばらく待ってください。`);
      return null;
    }

    if (error instanceof OpenAI.APIConnectionError) {
      console.error("ネットワーク接続エラー。インターネット接続を確認してください。");
      return null;
    }

    // その他の APIError
    if (error instanceof OpenAI.APIError) {
      console.error(`APIエラー (${error.status}): ${error.message}`);
      return null;
    }

    // SDK外の予期しないエラー
    throw error;
  }
}

const result = await safeCompletion("こんにちは");
if (result) console.log(result);

import OpenAI from "openai";
import { zodResponseFormat } from "openai/helpers/zod";
import { z } from "zod";

const client = new OpenAI();

// ── 出力スキーマ ─────────────────────────────────
const BlogMetaSchema = z.object({
  seoTitle: z
    .string()
    .describe("SEO最適化済みタイトル（32文字以内、キーワードを先頭に）"),
  metaDescription: z
    .string()
    .describe("メタディスクリプション（80〜120字、CTA含む）"),
  slug: z
    .string()
    .describe("URLスラッグ（英小文字・ハイフン区切り）"),
  tags: z
    .array(z.string())
    .describe("関連タグ（5件以内）"),
  category: z
    .enum(["typescript", "javascript", "css", "python", "sql", "bat", "ai"])
    .describe("最も適したカテゴリ"),
  difficulty: z
    .enum(["beginner", "intermediate", "advanced"])
    .describe("対象読者の技術レベル"),
  internalLinkSuggestion: z
    .string()
    .describe("関連する記事として内部リンクを貼るとよいキーワード"),
});

type BlogMeta = z.infer<typeof BlogMetaSchema>;

// ── メタデータ生成関数 ────────────────────────────
async function generateBlogMeta(articleContent: string): Promise<BlogMeta> {
  console.log("メタデータを生成中...
");

  const response = await client.beta.chat.completions.parse({
    model: "gpt-4o",
    messages: [
      {
        role: "system",
        content: `あなたはSEO専門のコンテンツストラテジストです。
与えられた技術ブログ記事を分析し、SEO効果の高いメタデータを日本語で生成してください。
タイトルは検索意図に合わせ、メタディスクリプションはクリック率を高める文章にしてください。`,
      },
      {
        role: "user",
        content: `以下の記事のメタデータを生成してください：

${articleContent}`,
      },
    ],
    response_format: zodResponseFormat(BlogMetaSchema, "blog_meta"),
  });

  const meta = response.choices[0].message.parsed;
  if (!meta) throw new Error("メタデータの生成に失敗しました");

  return meta;
}

// ── 実行例 ───────────────────────────────────────
const sampleArticle = `
TypeScriptのジェネリクスは、型を引数として受け取る機能です。
<T>という記法を使い、さまざまな型に対応した汎用的な関数やクラスを作れます。
例えば、配列の最初の要素を返すfirst<T>(arr: T[]): T関数は
どんな型の配列にも使えます。実務では、APIレスポンスの型定義や
状態管理のストアなどでよく活用されます。
`;

try {
  const meta = await generateBlogMeta(sampleArticle);

  console.log("=== 生成されたメタデータ ===");
  console.log("SEOタイトル:", meta.seoTitle);
  console.log("メタディスクリプション:", meta.metaDescription);
  console.log("スラッグ:", meta.slug);
  console.log("タグ:", meta.tags.join(", "));
  console.log("カテゴリ:", meta.category);
  console.log("難易度:", meta.difficulty);
  console.log("内部リンク候補:", meta.internalLinkSuggestion);
} catch (error) {
  if (error instanceof OpenAI.APIError) {
    console.error(`APIエラー: ${error.message}`);
  } else {
    throw error;
  }
}