How to Configure OpenAI Models with LangExtract: A Complete Guide

LangExtract automatically routes OpenAI model requests through its dedicated provider by matching model IDs against regex patterns in 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. 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. 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. 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:

• 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:

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:

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

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:

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:

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	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	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	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	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	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, 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. 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 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().

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}