OpenAI Setup
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
Section titled âPrerequisitesâ- A valid OpenAI account
- OpenAI API key from OpenAI Platform
- Access and quota for the supported models:
gpt-4ogpt-4o-minigpt-4.1gpt-4.1-minigpt-4.1-nanogpt-5gpt-5-minigpt-5-nanotext-embedding-3-smalltext-embedding-3-largewhisper-1
Environment Variables
Section titled â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
Section titled âConfigurationâFollow these steps to configure OpenAI integration:
Step 1: Create Kubernetes Secret
Section titled âStep 1: Create Kubernetes SecretâCreate a secret with your OpenAI API key:
apiVersion: v1kind: Secretmetadata: name: openai-credentialstype: OpaquestringData: OPENAI_API_KEY: "sk-your-openai-api-key-here"Apply the secret to your cluster:
kubectl apply -f openai-secret.yamlStep 2: Configure Helm Values
Section titled âStep 2: Configure Helm ValuesâReference the secret in your Helm configuration:
# External Secret (recommended)backend: config: existingOpenAiApiKeySecretName: "openai-credentials"
llamaParse: config: existingOpenAiApiKeySecretName: "openai-credentials"
######################################################################
# or direct configuration (not recommended for production)backend: config: openAiApiKey: "sk-your-openai-api-key-here" # Sets OPENAI_API_KEY
llamaParse: config: openAiApiKey: "sk-your-openai-api-key-here" # Sets OPENAI_API_KEYVerification
Section titled â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
Section titled âTroubleshootingâCommon Issues
Section titled âCommon IssuesâAPI Key Invalid
Section titled âAPI Key InvalidâError: Incorrect API key providedSolution: Verify your API key is correct and active in the OpenAI Platform
Rate Limiting
Section titled âRate LimitingâError: Rate limit exceededSolution:
- Check your OpenAI usage limits
- Consider upgrading your OpenAI plan
- Implement request throttling if needed
Quota Exceeded
Section titled âQuota ExceededâError: You exceeded your current quotaSolution:
- Check your OpenAI billing and usage
- Add credits to your OpenAI account
- Set up billing alerts
Model Access Issues
Section titled âModel Access IssuesâError: The model 'gpt-4o' does not exist or you do not have access to itSolution:
- Verify model availability in your region
- Check if you have access to the specific model
Debug Steps
Section titled âDebug Stepsâ-
Test API key directly:
Terminal window curl https://api.openai.com/v1/models \-H "Authorization: Bearer $OPENAI_API_KEY" -
Check secret mounting:
Terminal window kubectl describe pod <llamacloud-pod-name> | grep -A 10 "Environment" -
Verify network connectivity: Ensure your cluster can reach
api.openai.com