LlamaCloud 支持 Azure OpenAI，作为 OpenAI 面向企业级的替代方案，供那些要求更强合规、安全与私有部署的组织使用。本页指导你为自托管的 LlamaCloud 部署配置 Azure OpenAI 集成。

前置条件

• 一个有效的 Azure OpenAI 账号

• 已在 Azure 里部署好的 Azure OpenAI 资源

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

  • 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

环境变量

Azure OpenAI 支持按模型逐个配置环境变量。每个模型使用自己的一套凭据：

环境变量的命名模式

• AZURE_OPENAI_<MODEL_NAME>_API_KEY —— 部署（deployment）的 API key
• AZURE_OPENAI_<MODEL_NAME>_BASE_URL —— Azure OpenAI 端点
• AZURE_OPENAI_<MODEL_NAME>_DEPLOYMENT_NAME —— 部署名（不是模型名）
• AZURE_OPENAI_<MODEL_NAME>_API_VERSION —— API 版本

受支持的模型

• GPT-4o: AZURE_OPENAI_GPT_4O_*
• GPT-4o Mini: AZURE_OPENAI_GPT_4O_MINI_*
• GPT-4.1: AZURE_OPENAI_GPT_4_1_*
• GPT-4.1 Mini: AZURE_OPENAI_GPT_4_1_MINI_*
• GPT-4.1 Nano: AZURE_OPENAI_GPT_4_1_NANO_*
• GPT-5: AZURE_OPENAI_GPT_5_*
• GPT-5 Mini: AZURE_OPENAI_GPT_5_MINI_*
• GPT-5 Nano: AZURE_OPENAI_GPT_5_NANO_*
• Text Embedding 3 Small: AZURE_OPENAI_TEXT_EMBEDDING_3_SMALL_*
• Text Embedding 3 Large: AZURE_OPENAI_TEXT_EMBEDDING_3_LARGE_*
• Whisper 1: AZURE_OPENAI_WHISPER_1_*

配置

Azure OpenAI 采用按模型的配置，每个模型各有独立凭据。请按下列步骤操作：

第 1 步：备齐 Azure OpenAI 的信息

对你想使用的每个模型，收集：

• API Key：来自你的 Azure OpenAI 资源的 “Keys and Endpoint” 一节
• Base URL：你的 Azure 端点（例如 https://your-resource.openai.azure.com）
• Deployment Name：你的模型部署名（不是模型名）
• API Version：当前版本为 2024-12-01-preview

第 2 步：创建 Kubernetes Secret

为每个模型用你的 Azure OpenAI 凭据创建一个 secret：

apiVersion: v1
kind: Secret
metadata:
  name: azure-openai-credentials
type: Opaque
stringData:
  # GPT-4o configuration
  AZURE_OPENAI_GPT_4O_API_KEY: "your-gpt-4o-api-key"
  AZURE_OPENAI_GPT_4O_BASE_URL: "https://your-resource.openai.azure.com"
  AZURE_OPENAI_GPT_4O_DEPLOYMENT_NAME: "your-gpt-4o-deployment"
  AZURE_OPENAI_GPT_4O_API_VERSION: "2024-12-01-preview"

  # GPT-4o Mini configuration
  AZURE_OPENAI_GPT_4O_MINI_API_KEY: "your-gpt-4o-mini-api-key"
  AZURE_OPENAI_GPT_4O_MINI_BASE_URL: "https://your-resource.openai.azure.com"
  AZURE_OPENAI_GPT_4O_MINI_DEPLOYMENT_NAME: "your-gpt-4o-mini-deployment"
  AZURE_OPENAI_GPT_4O_MINI_API_VERSION: "2024-12-01-preview"

  # Add other models as needed...

应用这个 secret：

终端窗口

kubectl apply -f azure-openai-secret.yaml

第 3 步：配置 Helm values

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

config:
  llms:
    azureOpenAi:
      secret: "azure-openai-credentials"

直接配置

config:
  llms:
    azureOpenAi:
      # baseUrl is your Azure OpenAI resource endpoint (see "Base URL" below),
      # not the OpenAI API. One entry per Azure deployment.
      deployments: []
      # - model: "gpt-5.4"
      #   deploymentName: "gpt-5.4"
      #   apiKey: "<AZURE-OPENAI-KEY>"
      #   baseUrl: "https://<your-resource>.openai.azure.com"
      #   apiVersion: "2025-04-01-preview"
      # - model: "gpt-5.4-mini"
      #   deploymentName: "gpt-5.4-mini"
      #   apiKey: "<AZURE-OPENAI-KEY>"
      #   baseUrl: "https://<your-resource>.openai.azure.com"
      #   apiVersion: "2025-04-01-preview"

到哪里找 Azure OpenAI 的配置值

Base URL

1. 在 Azure 门户里进入你的 Azure OpenAI 资源
2. 走到 Resource Management → Keys and Endpoint
3. 复制 Endpoint 的值（形如 https://your-resource.openai.azure.com）

API Key

1. 就在同一个 Keys and Endpoint 一节里
2. 复制 KEY 1 或 KEY 2 任意一个

Deployment Name

1. 进入你 Azure OpenAI 资源里的 Model deployments
2. 用的是 Deployment name，不是 Model name
3. 例如：若你有一个名为 “my-gpt-4o” 的部署、底层模型是 “gpt-4o”，那就填 “my-gpt-4o”

API Version

• 用最新的稳定版本：2024-12-01-preview
• 当前版本请查 Azure OpenAI API 参考

验证

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

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

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

故障排查

常见问题

认证错误

Error: Access denied due to invalid subscription key

解决办法：

• 确认 API key 正确
• 确认该 key 没有过期
• 确认你为这个部署用的是对的那个 key

找不到部署

Error: The API deployment for this resource does not exist

解决办法：

• 确认部署名与 Azure 里的完全一致
• 检查该部署与你的资源处于同一地域
• 确认该部署没有处于 paused 或 stopped 状态

API 版本问题

Error: Invalid API version specified

解决办法：

• 使用受支持的 API 版本（例如 2024-12-01-preview）
• 当前版本请查 Azure OpenAI 文档

被限流

Error: Rate limit exceeded

解决办法：

• 查看你的 Azure OpenAI 配额
• 考虑升级部署档位
• 做好请求节流

排查步骤

1. 直接测试端点：

   终端窗口

   curl -H "api-key: YOUR_KEY" \
        "https://YOUR_RESOURCE.openai.azure.com/openai/deployments/YOUR_DEPLOYMENT/completions?api-version=2024-12-01-preview"

2. 确认 secret 已挂载：

   终端窗口

   kubectl get secret your-azure-openai-secret -o yaml
   kubectl describe pod <pod-name> | grep -A 20 Environment

3. 检查网络连通性：确保你的集群能够访问你的 Azure OpenAI 端点