OpenAI Setup

Self-Hosting Documentation Access Granted

LlamaCloud supports OpenAI as the primary LLM provider for document parsing, extraction, and AI capabilities. This page guides you through configuring OpenAI integration with your self-hosted LlamaCloud deployment.

Prerequisites

A valid OpenAI account
OpenAI API key from OpenAI Platform
Access and quota for the supported models:
- gpt-4o
- gpt-4o-mini
- gpt-4.1
- gpt-4.1-mini
- gpt-4.1-nano
- gpt-5
- gpt-5-mini
- gpt-5-nano
- text-embedding-3-small
- text-embedding-3-large
- whisper-1

Environment Variables

The OpenAI integration uses these environment variables:

OPENAI_API_KEY - Your OpenAI API key for LlamaParse service (required)

Note: Both variables typically contain the same API key value but are used by different services within LlamaCloud.

Configuration

Follow these steps to configure OpenAI integration:

Step 1: Create Kubernetes Secret

Create a secret with your OpenAI API key:

apiVersion: v1
kind: Secret
metadata:
  name: openai-credentials
type: Opaque
stringData:
  OPENAI_API_KEY: "sk-your-openai-api-key-here"

Apply the secret to your cluster:

kubectl apply -f openai-secret.yaml

Step 2: Configure Helm Values

Reference the secret in your Helm configuration:

# External Secret (recommended)
config:
  llms:
    openAi:
      secret: "openai-credentials"

######################################################################

# or direct configuration (not recommended for production)
config:
  llms:
    openAi:
      apiKey: sk-your-openai-api-key-here"  # Sets OPENAI_API_KEY

Verification

After configuration, verify your OpenAI integration:

Verify in Admin UI: Check the LlamaCloud admin interface for available OpenAI models
Test parsing: Upload a document to confirm OpenAI models are working

Troubleshooting

Common Issues

API Key Invalid

Error: Incorrect API key provided

Solution: Verify your API key is correct and active in the OpenAI Platform

Rate Limiting

Error: Rate limit exceeded

Solution:

Check your OpenAI usage limits
Consider upgrading your OpenAI plan
Implement request throttling if needed

Quota Exceeded

Error: You exceeded your current quota

Solution:

Check your OpenAI billing and usage
Add credits to your OpenAI account
Set up billing alerts

Model Access Issues

Error: The model 'gpt-4o' does not exist or you do not have access to it

Solution:

Verify model availability in your region
Check if you have access to the specific model

Debug Steps

Test API key directly:

curl https://api.openai.com/v1/models \
  -H "Authorization: Bearer $OPENAI_API_KEY"

Check secret mounting:

kubectl describe pod <llamacloud-pod-name> | grep -A 10 "Environment"

Verify network connectivity: Ensure your cluster can reach api.openai.com