openai

OpenAI API integration — GPT models, embeddings, function calling, assistants, vision

SKILL.md

GitHub

OpenAI

OpenAI API integration -- GPT models, embeddings, function calling, assistants, vision.

When to Use

  • Calling GPT models for chat completions or text generation
  • Generating embeddings for vector search / RAG pipelines
  • Building assistants with threads, runs, and tool use
  • Image understanding with GPT-4o vision
  • Structured JSON output or function/tool calling

Key Patterns

Chat Completions

  • Messages array: [{ role: "system" | "user" | "assistant", content }]
  • Streaming: Use stream: true and consume SSE chunks via for await (const chunk of stream)
  • Function calling: Define tools with JSON Schema; model returns tool_calls to execute
  • Structured outputs: response_format: { type: "json_schema", json_schema: { ... } } for guaranteed schema

Embeddings

  • text-embedding-3-small (1536d, cheap) or text-embedding-3-large (3072d, precise)
  • Batch embed with input: string[] -- up to 2048 inputs per request
  • Use cosine similarity for retrieval; same model for docs and queries

Assistants API

  • Threads: Persistent conversation state managed server-side
  • Runs: Execute assistant on a thread; poll or stream for completion
  • Tools: code_interpreter, file_search, or custom function tools
  • File search: Built-in RAG with vector store attachments

Vision

  • Pass images as content: [{ type: "image_url", image_url: { url } }] in user messages
  • Supports base64 data URIs and HTTP URLs
  • Use detail: "low" | "high" | "auto" to control token cost

Rate Limiting and Retries

  • Respect 429 with exponential backoff (2^n seconds, jitter, max 60s)
  • Track x-ratelimit-remaining-* headers; use tiktoken to count tokens before sending

Fine-Tuning

  • Prepare JSONL with {"messages": [...]} per line; validate token counts before submitting
  • Upload file, create fine-tune job, monitor via events endpoint

Anti-Patterns

  • Ignoring token limits -- estimate usage with tiktoken before large prompts
  • Hardcoding model names -- use config/env vars for easy upgrades
  • Skipping error handling on streams -- network drops lose partial responses
  • Mixing embedding models between docs and queries
  • Polling assistant runs without backoff -- use streaming or exponential delay

Related Skills

ai-sdk | rag | prompt-engineering | ai-agents