0
# Chat Models
1

2
Modern conversational AI models supporting streaming, tools, structured output, and multimodal interactions. Built on OpenAI's Chat Completions API with support for the latest GPT models.
3

4
## Capabilities
5

6
### ChatOpenAI Class
7

8
The primary chat model class providing access to OpenAI's chat completion models with comprehensive feature support.
9

10
```typescript { .api }
11
/**
12
 * Main OpenAI chat model integration supporting both Completions and Responses APIs
13
 * Supports streaming, tool calling, structured output, and multimodal interactions
14
 */
15
class ChatOpenAI<CallOptions extends ChatOpenAICallOptions = ChatOpenAICallOptions> 
16
  extends BaseChatOpenAI<CallOptions> {
17
  
18
  constructor(fields?: ChatOpenAIFields & Partial<ChatOpenAIFields>);
19

20
  /** Model configuration */
21
  model: string; // Default: "gpt-3.5-turbo"
22
  temperature?: number; // Sampling temperature (0-2)
23
  maxTokens?: number; // Maximum tokens to generate
24
  topP?: number; // Nucleus sampling parameter
25
  frequencyPenalty?: number; // Frequency penalty (-2 to 2)
26
  presencePenalty?: number; // Presence penalty (-2 to 2)
27
  n?: number; // Number of completions to generate
28
  streaming: boolean; // Enable streaming (default: false)
29
  streamUsage: boolean; // Include usage in streams (default: true)
30
  logprobs?: boolean; // Return log probabilities
31
  topLogprobs?: number; // Number of top log probabilities (1-20)
32
  
33
  /** Advanced features */
34
  useResponsesApi: boolean; // Use Responses API (default: false)
35
  supportsStrictToolCalling?: boolean; // Enable strict tool calling
36
  audio?: OpenAIClient.Chat.ChatCompletionAudioParam; // Audio output config
37
  modalities?: Array<OpenAIClient.Chat.ChatCompletionModality>; // Output modalities
38
  reasoning?: OpenAIClient.Reasoning; // Reasoning model options
39
  zdrEnabled?: boolean; // Zero data retention mode
40
  service_tier?: string; // "auto" | "default" | "flex" | "priority"
41
  promptCacheKey?: string; // Cache key for prompt caching
42
  verbosity?: OpenAIVerbosityParam; // "low" | "medium" | "high" | null
43

44
  /** Generate a single response */
45
  invoke(
46
    input: BaseLanguageModelInput, 
47
    options?: CallOptions
48
  ): Promise<BaseMessage>;
49

50
  /** Generate streaming response */
51
  stream(
52
    input: BaseLanguageModelInput, 
53
    options?: CallOptions
54
  ): AsyncIterable<BaseMessageChunk>;
55

56
  /** Bind tools to the model */
57
  bindTools(
58
    tools: ChatOpenAIToolType[], 
59
    kwargs?: Partial<CallOptions>
60
  ): Runnable<BaseLanguageModelInput, BaseMessageLike>;
61

62
  /** Enable structured output with schema validation */
63
  withStructuredOutput<T>(
64
    outputSchema: z.ZodType<T> | Record<string, any>,
65
    config?: {
66
      name?: string;
67
      description?: string;
68
      method?: "functionCalling" | "jsonMode";
69
      strict?: boolean;
70
    }
71
  ): Runnable<BaseLanguageModelInput, T>;
72

73
  /** Configure model with runtime options */
74
  withConfig(config: RunnableConfig): Runnable;
75

76
  /** Internal generation method */
77
  _generate(
78
    messages: BaseMessage[], 
79
    options: CallOptions, 
80
    runManager?: CallbackManagerForLLMRun
81
  ): Promise<ChatResult>;
82
}
83
```
84

85
### Base Chat Model
86

87
Abstract base class providing common functionality for OpenAI chat models.
88

89
```typescript { .api }
90
/**
91
 * Abstract base class for OpenAI chat models
92
 * Implements common OpenAI functionality, authentication, and client configuration
93
 */
94
abstract class BaseChatOpenAI<CallOptions extends BaseChatOpenAICallOptions>
95
  extends BaseChatModel<CallOptions, AIMessageChunk> {
96

97
  /** Client configuration */
98
  openAIApiKey?: string; // OpenAI API key
99
  organization?: string; // OpenAI organization ID
100
  baseURL?: string; // Custom base URL
101
  timeout?: number; // Request timeout in milliseconds
102
  maxRetries?: number; // Maximum retry attempts
103
  dangerouslyAllowBrowser?: boolean; // Allow browser usage
104

105
  /** Advanced configuration */
106
  completionWithRetry<T>(
107
    request: OpenAIClient.Chat.ChatCompletionCreateParamsStreaming,
108
    options?: OpenAICallOptions
109
  ): Promise<T>;
110

111
  /** Convert messages to OpenAI format */
112
  _convertMessagesToOpenAIParams(
113
    messages: BaseMessage[],
114
    model?: string
115
  ): OpenAIClient.Chat.ChatCompletionMessageParam[];
116
}
117
```
118

119
## Usage Examples
120

121
### Basic Chat
122

123
```typescript
124
import { ChatOpenAI } from "@langchain/openai";
125

126
const chatModel = new ChatOpenAI({
127
  model: "gpt-4o-mini",
128
  temperature: 0.7,
129
  maxTokens: 1000,
130
  apiKey: process.env.OPENAI_API_KEY
131
});
132

133
// Simple message
134
const response = await chatModel.invoke("Explain quantum computing in simple terms");
135
console.log(response.content);
136

137
// Message with system prompt
138
import { HumanMessage, SystemMessage } from "@langchain/core/messages";
139

140
const messages = [
141
  new SystemMessage("You are a helpful AI assistant specializing in science education."),
142
  new HumanMessage("What is photosynthesis?")
143
];
144

145
const result = await chatModel.invoke(messages);
146
```
147

148
### Streaming Responses
149

150
```typescript
151
const streamingModel = new ChatOpenAI({
152
  model: "gpt-4o",
153
  streaming: true,
154
  temperature: 0.3
155
});
156

157
// Stream tokens as they arrive
158
const stream = await streamingModel.stream("Write a short story about space exploration");
159

160
for await (const chunk of stream) {
161
  process.stdout.write(chunk.content);
162
}
163
```
164

165
### Tool Calling
166

167
```typescript
168
import { z } from "zod";
169

170
// Define tools
171
const tools = [
172
  {
173
    name: "calculator",
174
    description: "Perform mathematical calculations",
175
    schema: z.object({
176
      operation: z.enum(["add", "subtract", "multiply", "divide"]),
177
      a: z.number().describe("First number"),
178
      b: z.number().describe("Second number")
179
    })
180
  },
181
  {
182
    name: "get_weather",
183
    description: "Get current weather for a location",
184
    schema: z.object({
185
      location: z.string().describe("City name"),
186
      units: z.enum(["celsius", "fahrenheit"]).optional()
187
    })
188
  }
189
];
190

191
const modelWithTools = chatModel.bindTools(tools);
192

193
// The model will automatically call tools when appropriate
194
const response = await modelWithTools.invoke("What's 15 * 23? Also, what's the weather in Tokyo?");
195

196
// Handle tool calls
197
if (response.tool_calls && response.tool_calls.length > 0) {
198
  for (const toolCall of response.tool_calls) {
199
    console.log(`Tool: ${toolCall.name}`);
200
    console.log(`Arguments: ${JSON.stringify(toolCall.args)}`);
201
  }
202
}
203
```
204

205
### Structured Output
206

207
```typescript
208
import { z } from "zod";
209

210
// Define output schema
211
const PersonSchema = z.object({
212
  name: z.string().describe("Person's full name"),
213
  age: z.number().describe("Person's age"),
214
  occupation: z.string().describe("Person's job or profession"),
215
  personality_traits: z.array(z.string()).describe("Key personality characteristics"),
216
  confidence: z.number().min(0).max(1).describe("Confidence in the analysis")
217
});
218

219
const structuredModel = chatModel.withStructuredOutput(PersonSchema, {
220
  name: "PersonAnalysis",
221
  description: "Extract person information from text",
222
  method: "functionCalling"
223
});
224

225
const result = await structuredModel.invoke(`
226
  John is a 34-year-old software engineer who works at a tech startup. 
227
  He's known for being creative, analytical, and having a great sense of humor. 
228
  He enjoys solving complex problems and mentoring junior developers.
229
`);
230

231
console.log(result);
232
// Output: { name: "John", age: 34, occupation: "software engineer", ... }
233
```
234

235
### Multimodal (Vision)
236

237
```typescript
238
import { HumanMessage } from "@langchain/core/messages";
239

240
const visionModel = new ChatOpenAI({
241
  model: "gpt-4o",
242
  maxTokens: 1000
243
});
244

245
const message = new HumanMessage({
246
  content: [
247
    {
248
      type: "text",
249
      text: "What do you see in this image? Describe it in detail."
250
    },
251
    {
252
      type: "image_url",
253
      image_url: {
254
        url: "https://example.com/image.jpg"
255
        // or use base64: "data:image/jpeg;base64,..."
256
      }
257
    }
258
  ]
259
});
260

261
const response = await visionModel.invoke([message]);
262
```
263

264
### Audio Output
265

266
```typescript
267
const audioModel = new ChatOpenAI({
268
  model: "gpt-4o-audio-preview",
269
  modalities: ["text", "audio"],
270
  audio: {
271
    voice: "alloy",
272
    format: "wav"
273
  }
274
});
275

276
const response = await audioModel.invoke("Tell me a joke and make it sound funny!");
277

278
// Response will include both text and audio
279
if (response.response_metadata?.audio) {
280
  // Handle audio data
281
  console.log("Audio data available:", response.response_metadata.audio.id);
282
}
283
```
284

285
### Configuration Options
286

287
```typescript
288
const advancedModel = new ChatOpenAI({
289
  // Model selection
290
  model: "gpt-4o",
291
  
292
  // Generation parameters
293
  temperature: 0.8,
294
  maxTokens: 2000,
295
  topP: 0.95,
296
  frequencyPenalty: 0.1,
297
  presencePenalty: 0.1,
298
  
299
  // API configuration
300
  apiKey: process.env.OPENAI_API_KEY,
301
  organization: process.env.OPENAI_ORG_ID,
302
  timeout: 60000, // 60 seconds
303
  maxRetries: 3,
304
  
305
  // Advanced features
306
  streaming: true,
307
  streamUsage: true,
308
  logprobs: true,
309
  topLogprobs: 5,
310
  
311
  // Performance options
312
  service_tier: "priority", // Higher priority processing
313
  promptCacheKey: "my-cache-key", // Enable prompt caching
314
  
315
  // Privacy and compliance
316
  zdrEnabled: true // Zero data retention
317
});
318
```
319

320
### Error Handling
321

322
```typescript
323
import { wrapOpenAIClientError } from "@langchain/openai";
324

325
try {
326
  const response = await chatModel.invoke("Hello!");
327
} catch (error) {
328
  // Errors are automatically wrapped with LangChain error handling
329
  if (error.code === 'invalid_api_key') {
330
    console.error("Invalid API key provided");
331
  } else if (error.code === 'rate_limit_exceeded') {
332
    console.error("Rate limit exceeded, please try again later");
333
  } else {
334
    console.error("Unexpected error:", error.message);
335
  }
336
}
337
```
338

339
## Call Options
340

341
### ChatOpenAICallOptions
342

343
Runtime options that can be passed to generation methods.
344

345
```typescript { .api }
346
interface ChatOpenAICallOptions extends BaseChatOpenAICallOptions {
347
  /** Tools available to the model */
348
  tools?: ChatOpenAIToolType[];
349
  
350
  /** Tool selection strategy */
351
  tool_choice?: OpenAIToolChoice | ResponsesToolChoice;
352
  
353
  /** Response format specification */
354
  response_format?: ChatOpenAIResponseFormat;
355
  
356
  /** Deterministic sampling seed */
357
  seed?: number;
358
  
359
  /** Streaming configuration */
360
  stream_options?: OpenAIClient.Chat.ChatCompletionStreamOptions;
361
  
362
  /** Enable parallel tool calling */
363
  parallel_tool_calls?: boolean;
364
  
365
  /** Enable strict mode for tools and schemas */
366
  strict?: boolean;
367
  
368
  /** Output modalities (text, audio) */
369
  modalities?: Array<OpenAIClient.Chat.ChatCompletionModality>;
370
  
371
  /** Audio output configuration */
372
  audio?: OpenAIClient.Chat.ChatCompletionAudioParam;
373
  
374
  /** Predicted output for optimization */
375
  prediction?: OpenAIClient.ChatCompletionPredictionContent;
376
  
377
  /** Reasoning model options */
378
  reasoning?: OpenAIClient.Reasoning;
379
  
380
  /** Service tier for processing priority */
381
  service_tier?: string;
382
  
383
  /** Prompt cache key */
384
  promptCacheKey?: string;
385
  
386
  /** Response verbosity level */
387
  verbosity?: OpenAIVerbosityParam;
388
}
389
```
390

391
## Model Support
392

393
### Available Models
394

395
The ChatOpenAI class supports all OpenAI chat models:
396

397
- **GPT-4o**: `gpt-4o`, `gpt-4o-2024-08-06`, `gpt-4o-2024-05-13`
398
- **GPT-4o mini**: `gpt-4o-mini`, `gpt-4o-mini-2024-07-18`
399
- **GPT-4 Turbo**: `gpt-4-turbo`, `gpt-4-turbo-2024-04-09`
400
- **GPT-4**: `gpt-4`, `gpt-4-0613`, `gpt-4-0314`
401
- **GPT-3.5 Turbo**: `gpt-3.5-turbo`, `gpt-3.5-turbo-0125`
402
- **Audio Models**: `gpt-4o-audio-preview`
403
- **Reasoning Models**: `o1-preview`, `o1-mini`
404

405
### Model Capabilities
406

407
Different models support different features:
408

409
| Feature | GPT-4o | GPT-4o mini | GPT-4 | GPT-3.5 | Audio | o1 |
410
|---------|--------|-------------|-------|---------|-------|-----|
411
| Function Calling | ✅ | ✅ | ✅ | ✅ | ✅ | ❌ |
412
| Vision | ✅ | ✅ | ✅ | ❌ | ✅ | ✅ |
413
| Audio Output | ❌ | ❌ | ❌ | ❌ | ✅ | ❌ |
414
| Structured Output | ✅ | ✅ | ✅ | ✅ | ✅ | ❌ |
415
| Reasoning | ❌ | ❌ | ❌ | ❌ | ❌ | ✅ |