# How to Configure OpenAI Models with LangExtract: A Complete Guide

> Configure OpenAI models with LangExtract easily. Learn how LangExtract automatically routes requests, handles formatting, and simplifies batch inference for your projects.

- Repository: [Google/langextract](https://github.com/google/langextract)
- Tags: how-to-guide
- Published: 2026-02-16

---

**LangExtract automatically routes OpenAI model requests through its dedicated provider by matching model IDs against regex patterns in [`langextract/providers/patterns.py`](https://github.com/google/langextract/blob/main/langextract/providers/patterns.py), then constructs an authenticated client that handles JSON/YAML formatting, parallel batch inference, and error mapping.**

To configure OpenAI models with LangExtract, you interact with the `langextract.providers.openai` module, which implements the provider interface defined in [`langextract/core/base_model.py`](https://github.com/google/langextract/blob/main/langextract/core/base_model.py). This guide explains the discovery mechanism, configuration parameters, and practical implementation patterns using the actual source code from the `google/langextract` repository.

## How LangExtract Discovers OpenAI Models

LangExtract uses a pattern-matching registry to select the appropriate provider for a given `model_id`. When you pass `model_id="gpt-4o"` to `lx.extract()`, the library executes the following discovery process:

1. **Pattern Matching**: The provider registry checks the requested identifier against the `OPENAI_PATTERNS` tuple defined in [`langextract/providers/patterns.py`](https://github.com/google/langextract/blob/main/langextract/providers/patterns.py). This tuple contains regular expressions such as `^gpt-4` and `^gpt4\.` that match all supported OpenAI model prefixes.

2. **Provider Instantiation**: Because the pattern matches, the registry instantiates the `OpenAILanguageModel` class from [`langextract/providers/openai.py`](https://github.com/google/langextract/blob/main/langextract/providers/openai.py). This class is registered via the `@router.register` decorator, which binds it to the factory function `langextract.core.base_model.create_model`.

## Configuring the OpenAI Provider

The `OpenAILanguageModel` constructor validates your configuration and builds an authenticated OpenAI client. You can configure the provider through environment variables or explicit arguments passed to `lx.extract()`.

### Authentication and Client Configuration

The provider accepts the following parameters in [`langextract/providers/openai.py`](https://github.com/google/langextract/blob/main/langextract/providers/openai.py):

- **`api_key`**: Your OpenAI secret key. The provider first checks the `OPENAI_API_KEY` environment variable, then falls back to `LANGEXTRACT_API_KEY`, and finally accepts an explicit `api_key` argument.
- **`base_url`**: Override the default OpenAI API endpoint. Use this for Azure OpenAI deployments or self-hosted proxies.
- **`organization`**: Optional organization ID for multi-tenant OpenAI accounts.

### Request Building and Format Control

When the provider constructs API requests, it performs the following operations as implemented in the source:

1. **System Message Injection**: The provider prepends a system message that forces JSON or YAML output based on the `format_type` parameter.
2. **Response Format Specification**: If `format_type` is `JSON`, the provider sets `response_format={"type": "json_object"}` in the chat completion payload. This instructs the model to return valid JSON without markdown fence characters.
3. **Parameter Forwarding**: All additional keyword arguments (such as `temperature`, `top_p`, `frequency_penalty`) are passed through to the OpenAI API unchanged.

### Parallel Inference for Batch Processing

For batch operations where `text_or_documents` contains multiple inputs, the provider uses a `ThreadPoolExecutor` with a default of **10 workers** to invoke the OpenAI endpoint concurrently. You can control this parallelism using the `max_workers` parameter.

## Configuration Options Reference

| Parameter | Description | Default |
|-----------|-------------|---------|
| `model_id` | OpenAI model identifier (e.g., `"gpt-4o"`, `"gpt-4o-mini"`). | `"gpt-4o-mini"` |
| `api_key` | OpenAI API key. Reads from `OPENAI_API_KEY` or `LANGEXTRACT_API_KEY` env vars if not provided. | *Required* |
| `base_url` | Custom API endpoint for Azure or proxy configurations. | `None` |
| `organization` | Organization ID for multi-tenant accounts. | `None` |
| `format_type` | Output structure: `lx.data.FormatType.JSON` or `YAML`. | `JSON` |
| `temperature` | Sampling randomness (0-2). | `None` (model default) |
| `max_workers` | Thread pool size for parallel batch inference. | `10` |
| `**kwargs` | Additional OpenAI parameters (`top_p`, `frequency_penalty`, etc.). | — |

## Practical Code Examples

### Basic Extraction with GPT-4o

This example demonstrates the minimal configuration required to extract structured data using OpenAI's GPT-4o model:

```python
import os
import langextract as lx
import textwrap

# Configure authentication via environment variable

os.environ["OPENAI_API_KEY"] = "sk-..."  # Never hardcode in production

prompt = textwrap.dedent("""\
    Extract every medication name and its dosage from the clinical note.
    Return a JSON list where each item has "name" and "dosage" fields.
""")

example = lx.data.ExampleData(
    text="Patient was prescribed ibuprofen 200mg twice daily.",
    extractions=[
        lx.data.Extraction(
            extraction_class="medication",
            extraction_text="ibuprofen",
            attributes={"dosage": "200mg"},
        )
    ],
)

result = lx.extract(
    text_or_documents="Patient was prescribed ibuprofen 200mg twice daily.",
    prompt_description=prompt,
    examples=[example],
    model_id="gpt-4o",  # Triggers OpenAI provider selection

    api_key=os.getenv("OPENAI_API_KEY"),
)

print(result.extractions)

```

### Using Environment Variables Only

For production deployments, omit the `api_key` argument and rely on environment variables. LangExtract checks `OPENAI_API_KEY` first, then falls back to `LANGEXTRACT_API_KEY`:

```bash
export OPENAI_API_KEY="sk-..."
export LANGEXTRACT_API_KEY="sk-..."  # Fallback option

```

```python
import langextract as lx

result = lx.extract(
    text_or_documents="Extract the date: Meeting scheduled for 2024-01-15.",
    prompt_description="Extract dates in ISO format.",
    examples=[],
    model_id="gpt-4o-mini",  # Uses default JSON format

)

```

### Batch Processing with Parallel Inference

Process multiple documents concurrently by passing a list to `text_or_documents`. The OpenAI provider automatically uses a `ThreadPoolExecutor` to parallelize requests:

```python
texts = [
    "Patient A: Prescribed aspirin 81mg daily.",
    "Patient B: Prescribed metformin 500mg twice daily.",
    "Patient C: Prescribed lisinopril 10mg once daily.",
]

batch_result = lx.extract(
    text_or_documents=texts,
    prompt_description="Extract medication names and dosages.",
    examples=[],
    model_id="gpt-4o",
    temperature=0.2,      # Lower temperature for consistency

    max_workers=5,        # Limit concurrent connections

)

```

### Requesting YAML Output

Change the output format by setting `format_type` to `YAML`. The provider adjusts the system prompt and disables the JSON schema enforcement:

```python
result = lx.extract(
    text_or_documents="Extract contact info: John Doe, john@example.com",
    prompt_description="Extract name and email.",
    examples=[],
    model_id="gpt-4o",
    format_type=lx.data.FormatType.YAML,  # Switches to YAML mode

)

```

## Key Source Files

Understanding the implementation details helps with advanced configuration and debugging:

| File | Role | Link |
|------|------|------|
| [`langextract/providers/openai.py`](https://github.com/google/langextract/blob/main/langextract/providers/openai.py) | Implements `OpenAILanguageModel` with client initialization, request building, parallel inference via `ThreadPoolExecutor`, and error handling. | https://github.com/google/langextract/blob/main/langextract/providers/openai.py |
| [`langextract/providers/patterns.py`](https://github.com/google/langextract/blob/main/langextract/providers/patterns.py) | Contains `OPENAI_PATTERNS` regex tuple that maps model IDs like `gpt-4o` to the OpenAI provider. | https://github.com/google/langextract/blob/main/langextract/providers/patterns.py |
| [`langextract/core/base_model.py`](https://github.com/google/langextract/blob/main/langextract/core/base_model.py) | Defines the abstract base class and `create_model` factory used by the provider registry. | https://github.com/google/langextract/blob/main/langextract/core/base_model.py |
| [`langextract/core/data.py`](https://github.com/google/langextract/blob/main/langextract/core/data.py) | Defines `FormatType` enum (`JSON`, `YAML`) and data structures for extractions. | https://github.com/google/langextract/blob/main/langextract/core/data.py |
| [`tests/provider_plugin_test.py`](https://github.com/google/langextract/blob/main/tests/provider_plugin_test.py) | Validates provider discovery and configuration parameter propagation. | https://github.com/google/langextract/blob/main/tests/provider_plugin_test.py |

## Summary

- **Automatic Discovery**: LangExtract selects the OpenAI provider by matching your `model_id` against regex patterns in [`langextract/providers/patterns.py`](https://github.com/google/langextract/blob/main/langextract/providers/patterns.py), requiring no manual provider registration.
- **Flexible Authentication**: Pass `api_key` explicitly or set `OPENAI_API_KEY`/`LANGEXTRACT_API_KEY` environment variables; optionally specify `base_url` for Azure or proxy configurations.
- **Format Control**: Set `format_type` to `JSON` (default) or `YAML` to enforce structured output; JSON mode automatically sets `response_format={"type": "json_object"}`.
- **Parallel Processing**: The provider uses a `ThreadPoolExecutor` with configurable `max_workers` (default 10) to process batch inputs concurrently.
- **Parameter Passthrough**: Additional OpenAI parameters like `temperature`, `top_p`, and `frequency_penalty` are forwarded transparently to the API.

## Frequently Asked Questions

### How does LangExtract know to use the OpenAI provider for my model ID?

LangExtract uses pattern matching defined in [`langextract/providers/patterns.py`](https://github.com/google/langextract/blob/main/langextract/providers/patterns.py). The `OPENAI_PATTERNS` tuple contains regular expressions like `^gpt-4` and `^gpt4\.` that match OpenAI model identifiers. When you pass `model_id="gpt-4o"`, the registry instantiates the `OpenAILanguageModel` class from [`langextract/providers/openai.py`](https://github.com/google/langextract/blob/main/langextract/providers/openai.py) automatically.

### Can I use Azure OpenAI or a custom proxy instead of the standard API?

Yes. Pass the `base_url` parameter to `lx.extract()` to override the default OpenAI endpoint. This configuration routes requests to Azure OpenAI deployments, self-hosted proxies, or other compatible APIs. You can also specify the `organization` parameter if your account requires multi-tenant authentication headers.

### What is the difference between `OPENAI_API_KEY` and `LANGEXTRACT_API_KEY` environment variables?

`OPENAI_API_KEY` is the primary variable checked by the OpenAI provider specifically for OpenAI-compatible endpoints. `LANGEXTRACT_API_KEY` serves as a generic fallback used by all providers when a service-specific key is not set. The provider checks `OPENAI_API_KEY` first, then `LANGEXTRACT_API_KEY`, and finally the explicit `api_key` argument passed to `lx.extract()`.