LlamaCloud 支持以 OpenAI 作为文档解析、抽取与 AI 能力的首选 LLM 提供方。本页指导你为自托管的 LlamaCloud 部署配置 OpenAI 集成。

前置条件

• 一个有效的 OpenAI 账号

• 来自 OpenAI Platform 的 OpenAI API key

• 所支持模型的访问权限与配额：

  • 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

环境变量

OpenAI 集成使用下列环境变量：

• OPENAI_API_KEY —— 供 LlamaParse 服务使用的 OpenAI API key（必需）

注意：这两个变量通常装的是同一个 API key 值，但由 LlamaCloud 内部的不同服务分别使用。

配置

按下列步骤配置 OpenAI 集成：

第 1 步：创建 Kubernetes Secret

用你的 OpenAI API key 创建一个 secret：

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

把这个 secret 应用到集群：

终端窗口

kubectl apply -f openai-secret.yaml

第 2 步：配置 Helm values

在你的 Helm 配置里引用这个 secret：

# 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

验证

配置完成后，请这样验证你的 OpenAI 集成：

1. 在管理界面核对：在 LlamaCloud 管理界面查看可用的 OpenAI 模型

2. 测试解析：上传一份文档，确认 OpenAI 模型确在工作

故障排查

常见问题

API key 无效

Error: Incorrect API key provided

解决办法：确认你的 API key 正确，且在 OpenAI Platform 里处于可用状态

被限流

Error: Rate limit exceeded

解决办法：

• 查看你的 OpenAI 用量上限
• 考虑升级你的 OpenAI 套餐
• 必要时做好请求节流

配额超限

Error: You exceeded your current quota

解决办法：

• 查看你的 OpenAI 计费与用量
• 为 OpenAI 账号充值
• 设好计费告警

模型访问问题

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

解决办法：

• 确认模型在你所在地域可用
• 检查你是否有该具体模型的使用权限

排查步骤

1. 直接测试 API key：

   终端窗口

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

2. 检查 secret 是否已挂载：

   终端窗口

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

3. 检查网络连通性：确保你的集群能够访问 api.openai.com