Azure 设置指南

Self-Hosting Documentation Access Granted

本指南帮助 Azure 用户将 LlamaCloud 连接到现有的 Azure 服务。它假设您已通过 Terraform、ARM 模板或其他方式配置了 Azure 基础设施，并重点介绍如何收集正确的凭据并配置 LlamaCloud 以连接到您的 Azure 服务。

概述

本指南涵盖将LlamaCloud连接到：

Azure Kubernetes 服务 (AKS) 用于容器编排
Azure Database for PostgreSQL 用于主数据存储
Azure Redis 缓存 用于缓存和会话
Azure Service Bus 用于作业队列管理
Azure Cosmos DB (MongoDB API) 用于文档存储
Azure Blob Storage 用于文件存储
Azure OpenAI 用于大语言模型集成
Microsoft Entra ID 用于身份验证 (OIDC)

前提条件

现有的 Azure 基础设施 已配置所需服务
AKS 集群 已配置 kubectl 访问权限
Helm v3.7.0+ 已安装
LlamaCloud License Key (contact support@llamaindex.ai)

步骤1：配置外部Azure服务

LlamaCloud 需要预配并配置以下 Azure 服务。点击下方各分区查看需求与凭证收集步骤：

Azure Database for PostgreSQL

点击展开 PostgreSQL 配置

要求：

版本: PostgreSQL 14 或更高版本
网络: 可从您的 AKS 集群访问
性能: 建议使用通用型或内存优化层级

收集凭据：

从 Azure 门户：

导航到您的 Azure Database for PostgreSQL 弹性服务器
前往设置 → 连接字符串
复制 ADO.NET 连接字符串（其格式将类似于下方所示）

连接字符串格式：

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

所需信息：

服务器全限定域名: your-server.postgres.database.azure.com
数据库名称: 通常为 llamacloud
用户名: 您的管理员用户名或专用LlamaCloud用户
密码: 用户的密码
端口: 5432 (默认)

确保启用 pgvector 扩展： 连接到您的数据库并启用向量扩展：

CREATE EXTENSION IF NOT EXISTS vector;

创建 PostgreSQL 密钥： 创建 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"

应用密钥：

kubectl apply -f postgresql-secret.yaml

Azure Redis 缓存

点击展开Redis配置

要求：

层级: 标准版或高级版（基础版不支持集群功能）
配置: 默认配置即可使用
网络: 可从您的AKS集群访问

收集凭据：

从 Azure 门户：

导航到您的 Azure Redis 缓存 实例
前往设置 → 访问密钥
复制主连接字符串

连接字符串格式：

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)
访问密钥: 来自门户网站的主访问密钥或辅助访问密钥

创建Redis密钥： 创建 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"

应用密钥：

kubectl apply -f redis-secret.yaml

Azure 服务总线

点击展开服务总线配置

要求：

层级: 标准或更高（基础层级缺少必要功能）
配置: 具有适当访问策略的命名空间
权限: 需要管理、发送和监听权限

收集凭据：

从 Azure 门户：

导航到您的 服务总线命名空间
前往设置 → 共享访问策略
选择或创建一个具有管理、发送和监听权限的策略
复制主连接字符串

连接字符串格式：

Endpoint=sb://your-namespace.servicebus.windows.net/;SharedAccessKeyName=RootManageSharedAccessKey;SharedAccessKey=your-key;EntityPath=your-queue

所需信息：

服务总线命名空间: your-namespace.servicebus.windows.net
策略名称: 您的共享访问策略名称
主键: 策略的访问密钥
队列名称: 如果策略具有管理权限，LlamaCloud将自动创建队列

创建服务总线密钥： 创建 servicebus-secret.yaml：

apiVersion: v1
kind: Secret
metadata:
  name: servicebus-secret
  namespace: default
type: Opaque
stringData:
  JOB_QUEUE_CONNECTION_STRING: "Endpoint=sb://your-namespace.servicebus.windows.net/;SharedAccessKeyName=your-policy-name;SharedAccessKey=your-access-key"

应用密钥：

kubectl apply -f servicebus-secret.yaml

Azure Cosmos DB (MongoDB API)

点击展开 Cosmos DB 配置

要求：

API: 必须使用 MongoDB API（而非 SQL API）
配置: 默认设置适用于大多数部署环境
网络: 可从您的AKS集群访问
性能: 预置吞吐量或无服务器

收集凭据：

从 Azure 门户：

导航到您的 Azure Cosmos DB 账户
验证其正在使用 MongoDB API（在概览中检查 API 类型）
前往设置 → 密钥
复制主连接字符串或辅助连接字符串

连接字符串格式：

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连接
自动扩缩容: 考虑为可变工作负载启用自动扩缩功能

创建 Cosmos DB 密钥： 创建 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@"

应用密钥：

kubectl apply -f cosmosdb-secret.yaml

Azure Blob 存储

点击展开 Blob 存储配置

要求：

性能: 标准性能层级已足够
访问方式: 账户密钥或托管身份访问

所需存储容器：

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 门户：

导航到您的存储账户
前往 安全与网络 → 访问密钥
复制存储账户名称和密钥（密钥1或密钥2）

所需信息：

存储账户名称: 你的存储账户名称
存储账户密钥: 主访问密钥或辅助访问密钥
存储端点: 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存储密钥： 创建 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"

应用密钥：

kubectl apply -f blobstorage-secret.yaml

Azure OpenAI

点击展开 Azure OpenAI 配置

要求：

所需模型: gpt-4o, gpt-4o-mini, 或其他支持的模型
部署: 模型必须完成部署，而不仅仅是可用状态

收集凭据：

如果使用 Azure OpenAI 而非 OpenAI API：

从 Azure 门户：

导航到您的 Azure OpenAI 资源
前往 资源管理 → 密钥与终结点
复制端点和 密钥 1 或 密钥 2
前往模型部署获取部署名称

每个模型所需信息：

端点: https://your-resource.openai.azure.com
API密钥: 访问密钥之一
部署名称: 实际的部署名称（默认为模型名称，例如 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 密钥： 创建 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"

应用密钥：

kubectl apply -f azure-openai-secret.yaml

步骤2：配置 Microsoft Entra ID (OIDC)

点击展开 Microsoft Entra ID OIDC 配置步骤

对于 Microsoft Entra ID 身份验证：

导航至 Microsoft Entra ID → 应用注册
查找或创建您的应用程序注册
配置重定向URI：

在“选择平台”下，选择“网页版”（非单页应用！）
如果您正在进行端口转发：http://localhost:3000/api/v1/auth/callback
如果您已配置入口：https://<internal-domain-for-llamacloud>/api/v1/auth/callback

前往概览获取应用程序(客户端) ID
前往证书与密钥获取或创建客户端密钥
从概览页面记下您的租户ID

Entra ID App registration

所需信息：

租户ID: 您的 Microsoft Entra ID 租户 ID
客户端 ID: 应用程序（客户端）ID
客户端密钥: 密钥值（非密钥ID）
发现网址: https://login.microsoftonline.com/{tenant-id}/v2.0/.well-known/openid-configuration

OIDC配置将直接在您的Helm值文件中设置，其中包含客户端密钥。

步骤3：创建许可证密钥机密

联系您的 LlamaIndex 客户经理（或 enterprise-support@runllama.ai）获取您的 LlamaCloud 许可证密钥。

创建您的LlamaCloud许可证密钥密钥：

创建 license-secret.yaml：

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

应用密钥：

kubectl apply -f license-secret.yaml

步骤4：配置Helm值

创建您的 azure-values.yaml 文件并配置相应设置：

完成 Azure 配置：

license:
  secret: "license-secret"

# External Azure services
postgresql:
  secret: "postgresql-secret"
redis:
  secret: "redis-secret"
rabbitmq:
  secret: "servicebus-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>

注意大语言模型提供商选项： 虽然本指南使用 Azure OpenAI，但 LlamaCloud 支持众多大语言模型提供商，包括但不限于：

OpenAI (GPT-4o, GPT-4.1, GPT-5, …)
Anthropic (Claude 4.0 Sonnet, Claude 3 Opus, …)
谷歌 (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

后续步骤

验证指南 - 验证您的部署是否正常运行
故障排除指南 - 常见问题与解决方案

如需更多配置选项和高级设置，请参阅主文档中的详细配置指南。

Azure 设置指南

自托管文档访问

概述

前提条件

步骤1：配置外部Azure服务

Azure Database for PostgreSQL

要求：

收集凭据：

Azure Redis 缓存

要求：

收集凭据：

Azure 服务总线

要求：

收集凭据：

Azure Cosmos DB (MongoDB API)

要求：

收集凭据：

Azure Blob 存储

要求：

所需存储容器：

收集凭据：

Azure OpenAI

要求：

收集凭据：

步骤2：配置 Microsoft Entra ID (OIDC)

对于 Microsoft Entra ID 身份验证：

所需信息：

步骤3：创建许可证密钥机密

步骤4：配置Helm值

完成 Azure 配置：

步骤5：部署LlamaCloud

后续步骤