Azure 配置指南 | BytesRouter

本指南帮助 Azure 技术栈的团队把 LlamaCloud 接到已有的 Azure 服务上。它假定你的 Azure 基础设施已经供给完毕（通过 Terraform、ARM 模板或其他手段），重点在于取到正确的凭据、并把 LlamaCloud 配置成连到你的 Azure 服务上。

概述

本指南覆盖把 LlamaCloud 连到下列服务：

Azure Kubernetes Service (AKS) 负责容器编排
Azure Database for PostgreSQL 负责主数据存储
Azure Cache for Redis 负责缓存与会话
Azure Cosmos DB (MongoDB API) 负责文档存储
Azure Blob Storage 负责文件存储
Azure OpenAI 负责 LLM 集成
Microsoft Entra ID 负责认证（OIDC）

前置条件

已有所需服务的既有 Azure 基础设施
AKS 集群，且已配好 kubectl 访问
已安装 Helm v3.7.0+
LlamaCloud 许可证 key（联系 support@llamaindex.ai）

第 1 步：配置外部 Azure 服务

LlamaCloud 需要下列 Azure 服务已供给并配置好。点开下面每一节即可查看要求与取凭据的步骤：

Azure Database for PostgreSQL

点开查看 PostgreSQL 的配置要求

要求：

版本：PostgreSQL 14 或更高
网络：可从你的 AKS 集群访问
性能：推荐 General Purpose 或 Memory Optimized 档位

取凭据：

在 Azure 门户里：

进入你的 Azure Database for PostgreSQL Flexible Server
走到 Settings → Connection strings
复制 ADO.NET 那条连接串（形如下面这样）

连接串的形态：

postgresql://username:password@servername.postgres.database.azure.com:5432/databasename

需要的信息：

服务器 FQDN：your-server.postgres.database.azure.com
数据库名：通常就是 llamacloud
用户名：你的管理员用户名，或专为 LlamaCloud 建的用户
密码：该用户的密码
端口：5432（默认）

务必启用 pgvector 扩展： 连上你的数据库并开启向量扩展：

CREATE EXTENSION IF NOT EXISTS vector;

创建 PostgreSQL Secret： 新建 postgresql-secret.yaml：

apiVersion: v1
kind: Secret
metadata:
  name: postgresql-secret
  namespace: default
type: Opaque
stringData:
  DATABASE_HOST: "your-server.postgres.database.azure.com"
  DATABASE_PORT: "5432"
  DATABASE_NAME: "llamacloud"
  DATABASE_USER: "your-username"
  DATABASE_PASSWORD: "your-password"

应用这个 secret：

终端窗口

kubectl apply -f postgresql-secret.yaml

Azure Cache for Redis

点开查看 Redis 的配置要求

要求：

档位：Standard 或 Premium（Basic 不支持集群）
配置：默认配置即可
网络：可从你的 AKS 集群访问

取凭据：

在 Azure 门户里：

进入你的 Azure Cache for Redis 实例
走到 Settings → Access keys
复制 Primary connection string

连接串的形态：

redis://your-redis-name.redis.cache.windows.net:6380

用于 SSL 连接（推荐）：

rediss://your-redis-name.redis.cache.windows.net:6380,password=your-primary-access-key,ssl=True

需要的信息：

Redis 主机：your-redis-name.redis.cache.windows.net
端口：6380（SSL）或 6379（非 SSL）
Access Key：门户里的主密钥或次密钥

创建 Redis Secret： 新建 redis-secret.yaml：

apiVersion: v1
kind: Secret
metadata:
  name: redis-secret
  namespace: default
type: Opaque
stringData:
  REDIS_SCHEME: "rediss"  # Use "redis" for non-SSL
  REDIS_HOST: "your-redis-name.redis.cache.windows.net"
  REDIS_PORT: "6380"      # Use "6379" for non-SSL
  REDIS_PASSWORD: "your-primary-access-key"

应用这个 secret：

终端窗口

kubectl apply -f redis-secret.yaml

Azure Cosmos DB (MongoDB API)

点开查看 Cosmos DB 的配置要求

要求：

API：必须使用 MongoDB API（不是 SQL API）
配置：多数部署用默认设置即可
网络：可从你的 AKS 集群访问
性能：预配吞吐量或 serverless

取凭据：

在 Azure 门户里：

进入你的 Azure Cosmos DB 账号
确认它用的是 MongoDB API（在 Overview 里查看 API 类型）
走到 Settings → Keys
复制 Primary Connection String 或 Secondary Connection String

连接串的形态：

mongodb://account-name:primary-key@account-name.mongo.cosmos.azure.com:10255/?ssl=true&replicaSet=globaldb&retrywrites=false&maxIdleTimeMS=120000&appName=@account-name@

需要的信息：

账号名：你的 Cosmos DB 账号名
主密钥：门户里的主密钥或次密钥
连接串：完整的 MongoDB 连接串（推荐）
数据库名：llamacloud 数据库会由 LlamaCloud 自动创建

重要说明：

必须用 MongoDB API：SQL API 或其他 API 都不可用
必须 SSL：Azure Cosmos DB 要求 SSL 连接
自动伸缩：负载起伏较大时考虑开启 auto-scale

创建 Cosmos DB Secret： 新建 cosmosdb-secret.yaml：

apiVersion: v1
kind: Secret
metadata:
  name: cosmosdb-secret
  namespace: default
type: Opaque
stringData:
  MONGODB_URL: "mongodb://your-account:your-primary-key@your-account.mongo.cosmos.azure.com:10255/?ssl=true&replicaSet=globaldb&retrywrites=false&maxIdleTimeMS=120000&appName=@your-account@"

应用这个 secret：

终端窗口

kubectl apply -f cosmosdb-secret.yaml

Azure Blob Storage

点开查看 Blob Storage 的配置要求

要求：

性能：Standard 性能档就够用
访问方式：账号密钥或托管身份（managed identity）

必需的存储容器：

LlamaCloud 要求你的存储账号里存在这些容器：

llama-platform-parsed-documents
llama-platform-etl
llama-platform-external-components
llama-platform-file-parsing
llama-platform-raw-files
llama-cloud-parse-output
llama-platform-file-screenshots
llama-platform-extract-output

取凭据：

在 Azure 门户里：

进入你的 Storage Account
走到 Security + networking → Access keys
复制 Storage account name 与 Key（key1 或 key2）

需要的信息：

存储账号名：你的存储账号名称
存储账号密钥：主访问密钥或次访问密钥
存储端点：https://yourstorageaccount.blob.core.windows.net
Azure 地域：存储账号所在地域（例如 eastus、westus2）

必需的存储容器： LlamaCloud 要求你的存储账号里存在这些容器：

llama-platform-parsed-documents
llama-platform-etl
llama-platform-external-components
llama-platform-file-parsing
llama-platform-raw-files
llama-cloud-parse-output
llama-platform-file-screenshots
llama-platform-extract-output

创建 Blob Storage Secret： 新建 blobstorage-secret.yaml：

apiVersion: v1
kind: Secret
metadata:
  name: blobstorage-secret
  namespace: default
type: Opaque
stringData:
  JCLOUDS_IDENTITY: "your-storage-account-name"
  JCLOUDS_CREDENTIAL: "your-storage-account-key"
  JCLOUDS_REGION: "eastus"  # Change to your Azure region
  JCLOUDS_ENDPOINT: "https://yourstorageaccount.blob.core.windows.net"

应用这个 secret：

终端窗口

kubectl apply -f blobstorage-secret.yaml

Azure OpenAI

点开查看 Azure OpenAI 的配置要求

要求：

必需模型：gpt-4o、gpt-4o-mini 或其他受支持的模型
部署：模型必须已经部署，而不只是可用

取凭据：

若用 Azure OpenAI 而非 OpenAI API：

在 Azure 门户里：

进入你的 Azure OpenAI 资源
走到 Resource Management → Keys and Endpoint
复制 Endpoint 与 KEY 1 或 KEY 2
到 Model deployments 取部署名

每个模型需要的信息：

端点：https://your-resource.openai.azure.com
API Key：两个访问密钥之一
部署名：实际的部署名（默认可能就叫模型名，例如 gpt-4o-mini；也可能是自定义名，例如 our-fast-gpt）
API 版本：用 2024-12-01-preview 或更新的版本

部署名映射示例：

Model: gpt-4o → Deployment Name: my-gpt-4o-deployment
Model: gpt-4o-mini → Deployment Name: my-gpt-4o-mini-deployment

创建 Azure OpenAI Secret： 新建 azure-openai-secret.yaml：

apiVersion: v1
kind: Secret
metadata:
  name: azure-openai-secret
  namespace: default
type: Opaque
stringData:
  AZURE_OPENAI_GPT_4O_API_KEY: "your-api-key"
  AZURE_OPENAI_GPT_4O_BASE_URL: "https://your-resource.openai.azure.com"
  AZURE_OPENAI_GPT_4O_DEPLOYMENT_NAME: "your-gpt-4o-deployment-name"
  AZURE_OPENAI_GPT_4O_API_VERSION: "2024-12-01-preview"
  # Add additional models as needed:
  # AZURE_OPENAI_GPT_4O_MINI_API_KEY: "your-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-name"
  # AZURE_OPENAI_GPT_4O_MINI_API_VERSION: "2024-12-01-preview"

应用这个 secret：

终端窗口

kubectl apply -f azure-openai-secret.yaml

第 2 步：配置 Microsoft Entra ID（OIDC）

点开查看 Microsoft Entra ID 的 OIDC 配置步骤

使用 Microsoft Entra ID 认证时：

进入 Microsoft Entra ID → App registrations
找到或创建你的应用注册
配置 redirect URI：

在平台选择上：Select a platform” 下选择 “Web”（不是 SPA！）
若你在做端口转发：http://localhost:3000/api/v1/auth/callback
若你已配好 ingress：https://<internal-domain-for-llamacloud>/api/v1/auth/callback

到 Overview 取 Application (client) ID
到 Certificates & secrets 取或创建一个 client secret
记下 Overview 页上的 Tenant ID

Entra ID 应用注册

需要的信息：

Tenant ID：你的 Microsoft Entra ID 租户 ID
Client ID：Application (client) ID
Client Secret：密钥的值（不是 secret ID）
Discovery URL：https://login.microsoftonline.com/{tenant-id}/v2.0/.well-known/openid-configuration

OIDC 配置会直接写进你的 Helm values 文件，其中包含这个 client secret。

第 3 步：创建许可证 key 的 Secret

联系你的 LlamaIndex 客户负责人（或 enterprise-support@runllama.ai）以取得你的 LlamaCloud 许可证 key。

创建你的 LlamaCloud 许可证 key secret：

新建 license-secret.yaml：

apiVersion: v1
kind: Secret
metadata:
  name: license-secret
  namespace: default
type: Opaque
stringData:
  license-key: <LLAMACLOUD-LICENSE-KEY>

应用这个 secret：

终端窗口

kubectl apply -f license-secret.yaml

第 4 步：配置 Helm values

新建你的 azure-values.yaml，按合适的内容配置：

完整的 Azure 配置：

license:
  secret: "license-secret"

# External Azure services
postgresql:
  secret: "postgresql-secret"
redis:
  secret: "redis-secret"
mongodb:
  secret: "cosmosdb-secret"

config:
  authentication:
    # Microsoft Entra ID OIDC configuration
    oidc:
      enabled: true
      discoveryUrl: "https://login.microsoftonline.com/<TENANT-ID>/v2.0/.well-known/openid-configuration"
      clientId: <CLIENT-ID>
      clientSecret: <CLIENT-SECRET>

  llms:
    # Azure OpenAI via secrets (or use OpenAI secret if preferred)
    azureOpenAi:
      secret: "azure-openai-credentials"

  storageBuckets:
    provider: "azure"
    # S3Proxy for Azure Blob Storage
    s3proxy:
      config:
        S3PROXY_ENDPOINT: "http://0.0.0.0:80"
        S3PROXY_AUTHORIZATION: "none"
        S3PROXY_IGNORE_UNKNOWN_HEADERS: "true"
        S3PROXY_CORS_ALLOW_ORIGINS: "*"
        JCLOUDS_PROVIDER: "azureblob"
        JCLOUDS_AZUREBLOB_AUTH: "azureKey"
        AZURE_STORAGE_ACCOUNT: <AZURE-STORAGE-ACCOUNT>
        AZURE_STORAGE_KEY: <AZURE-STORAGE-KEY>

关于 LLM 提供方的说明： 本指南用的是 Azure OpenAI，但 LlamaCloud 支持许多 LLM 提供方，包括但不限于：

OpenAI（GPT-4o、GPT-4.1、GPT-5，…）
Anthropic（Claude 4.0 Sonnet、Claude 3 Opus，…）
Google（Gemini 2.5 Pro、Gemini 2.0 Flash，…）

其他提供方的完整配置说明，见 LLM 集成总览。

第 5 步：部署 LlamaCloud

终端窗口

# Add Helm repository
helm repo add llamaindex https://run-llama.github.io/helm-charts
helm repo update

# Install LlamaCloud
helm install llamacloud llamaindex/llamacloud -f azure-values.yaml --namespace llamacloud

# Monitor deployment
kubectl get pods --namespace llamacloud -w

下一步

验证指南 —— 确认你的部署工作正常
排障指南 —— 常见问题与解决办法

更多配置项与进阶部署方式，请参考主文档里的详细配置指南。

索引

数据加载

查询

存储

成本分析

应用

聊天机器人

问答

结构化数据

智能体

Chat Engines

Query Engine

连接器

文档与节点

摄取流水线

节点解析器

大语言模型

提示词

回调

节点后处理器

响应合成器

检索器

路由

结构化输出

现有数据

Presets and Modes

能力

起步

能力

Examples

Azure Deployment

Databases and Queues

LLM Integrations

概述

前置条件

第 1 步：配置外部 Azure 服务

Azure Database for PostgreSQL

要求：

取凭据：

Azure Cache for Redis

要求：

取凭据：

Azure Cosmos DB (MongoDB API)

要求：

取凭据：

Azure Blob Storage

要求：

必需的存储容器：

取凭据：

Azure OpenAI

要求：

取凭据：

第 2 步：配置 Microsoft Entra ID（OIDC）

使用 Microsoft Entra ID 认证时：

需要的信息：

第 3 步：创建许可证 key 的 Secret

第 4 步：配置 Helm values

完整的 Azure 配置：

第 5 步：部署 LlamaCloud

下一步

友情链接