OpenAI Setup

Self-Hosting Documentation Access

This section requires a password to access. Interested in self-hosting? Contact sales to learn more.

Password:

Access Documentation

Self-Hosting Documentation Access Granted Logout

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:

1. Verify in Admin UI: Check the LlamaCloud admin interface for available OpenAI models

2. 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

1. Test API key directly:

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

2. Check secret mounting:

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

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