BytesRouter

主题

LlamaParse 文档版本 跟随上游 源快照 776a8ed8 更新于 2026-10-17

本指南帮你诊断并解决在 Azure 上部署 LlamaCloud 时的常见问题。若你在完成Azure 配置指南后遇到了麻烦，请用它排查。

通用调试命令

pod 状态与日志

终端窗口

# Check all pod status
kubectl get pods -n llamacloud -o wide

# Describe problematic pods
kubectl describe pod <pod-name> -n llamacloud

# Check logs for specific services
kubectl -n llamacloud logs deployment/llamacloud-telemetry
kubectl -n llamacloud logs deployment/llamacloud-temporal-parse
kubectl -n llamacloud logs deployment/llamacloud-web
kubectl -n llamacloud logs deployment/temporal-jobs-worker
kubectl -n llamacloud logs deployment/llamacloud-ocr
kubectl -n llamacloud logs deployment/llamacloud-s3proxy

服务与 Secret 状态

终端窗口

# Check services
kubectl get svc -n llamacloud

# Verify secrets exist
kubectl get secrets -n llamacloud

# Check configmaps
kubectl get configmaps -n llamacloud

数据库连接问题

PostgreSQL 连接问题

表现：

  • backend pod 起不来
  • 日志里出现数据库连接错误
  • 出现 “connection refused” 或 “timeout” 错误

解决办法：

  1. 确认数据库连接：

    终端窗口

    # Test connection from AKS
kubectl run -it --rm debug --image=postgres:15 --restart=Never -- psql "postgresql://username:password@server.postgres.database.azure.com:5432/llamacloud"

  2. 检查 secret 的值：

    终端窗口

    kubectl get secret postgresql-secret -o yaml
# Verify DATABASE_HOST, DATABASE_USER, etc. are correct

  3. 常见修法：

    • 把 AKS 的网段加入 PostgreSQL 的防火墙规则
    • 确认已启用 SSL（Azure Database for PostgreSQL 要求如此）
    • 检查数据库名是否存在
    • 核实用户的权限

Redis 连接问题

表现：

  • backend 日志里出现 “Redis connection failed”
  • 认证错误
  • SSL/TLS 错误

解决办法：

  1. 测试 Redis 连通性：

    终端窗口

    kubectl run -it --rm redis-test --image=redis:7 --restart=Never -- redis-cli -h your-redis.redis.cache.windows.net -p 6380 --tls -a your-access-key ping

  2. 检查 SSL 配置：

    • Azure Redis 要求在 6380 端口上使用 SSL
    • 确认 secret 里 REDIS_SCHEME: "rediss"
    • 走 SSL 时要确保 REDIS_PORT: "6380"

  3. 核实访问密钥：

    • 从 Azure 门户原样复制主访问密钥
    • 不要有多余的空格或字符

Cosmos DB（MongoDB）问题

表现：

  • MongoDB 连接错误
  • “SSL/TLS handshake failed”
  • “API type not supported”

解决办法：

  1. 确认用的是 MongoDB API：

    • 必须使用 MongoDB API，而不是 SQL API
    • 在 Cosmos DB 的 Overview 里查看 API 类型

  2. 检查连接串：

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

  3. SSL 要求：

    • Cosmos DB 必须用 SSL
    • 连接串里要带 ssl=true

存储问题

Blob Storage / S3Proxy 问题

表现：

  • 文件上传失败
  • S3Proxy pod 反复崩溃重启
  • “Access denied” 错误

解决办法：

  1. 查看 s3proxy 日志：

    终端窗口

    kubectl logs deployment/llamacloud-s3proxy -n llamacloud

  2. 核实容器名：

    • 所有必需的容器都要存在
    • 名字区分大小写
    • 在 Azure 门户里查看这些容器

  3. 必需的容器：

    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

  4. 检查 s3proxy 的配置：

Azure OpenAI 问题

模型部署问题

表现：

  • “Model not found” 错误
  • “Deployment not found” 错误
  • API 版本错误

解决办法：

  1. 查看 job service 日志：

    终端窗口

    kubectl logs deployment/llamacloud-operator -n llamacloud

    我们会在 pod 启动时运行 LLM 集成的校验器。关于 LLM 集成的有用错误日志可以在那里找到。

  2. 核实部署名：

    • 用的是部署名，不是模型名
    • 在 Azure 门户 → Model deployments 里查看

  3. 检查配额：

    • 确保分配了足够的 TPM 配额
    • 确认该部署没有被暂停

  4. API 版本：

    • 使用受支持的版本：2024-12-01-preview
    • 最新版本请查 Azure OpenAI 文档

  5. 直连测试：

    终端窗口

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

认证问题

Microsoft Entra ID 的 OIDC 问题

表现：

  • 认证跳转失败
  • “Invalid client” 错误
  • OIDC discovery 错误

解决办法：

  1. 核实应用注册：

    • 检查 client ID 是否正确
    • 确认 redirect URI 已配置
    • 确保 client secret 有效（未过期）

  2. 检查 discovery URL：

    https://login.microsoftonline.com/{tenant-id}/v2.0/.well-known/openid-configuration

  3. 测试 OIDC 端点：

    终端窗口

    curl https://login.microsoftonline.com/{tenant-id}/v2.0/.well-known/openid-configuration

各类 pod 自身的问题

backend pod 问题

常见问题：

  • 环境变量错误
  • Secret 挂载失败
  • 数据库迁移失败

排查步骤：

终端窗口

kubectl logs deployment/llamacloud --tail=100 -n llamacloud
kubectl describe deployment llamacloud -n llamacloud
kubectl get events --sort-by='.lastTimestamp' -n llamacloud

frontend pod 问题

常见问题：

  • 构建失败
  • 配置错误
  • ingress 连通性

排查步骤：

终端窗口

kubectl -n llamacloud logs deployment/llamacloud-web --tail=100
kubectl -n llamacloud port-forward svc/llamacloud-web 3000:80

jobs worker 问题

常见问题：

  • 队列连通性
  • 任务处理失败
  • Memory/CPU 上限

排查步骤：

终端窗口

kubectl -n llamacloud logs deployment/temporal-jobs-worker --tail=100
kubectl -n llamacloud top pod -l app.kubernetes.io/name=temporal-jobs-worker

网络与安全问题

AKS 网络问题

表现：

  • pod 无法访问 Azure 服务
  • DNS 解析失败
  • 连接时好时坏

解决办法：

  1. 检查网络安全组：

    • 确认出站规则放行了到 Azure 服务的连接
    • 检查子网的 NSG 规则

  2. 核实 DNS：

    终端窗口

    kubectl run -it --rm nslookup --image=busybox --restart=Never -- nslookup your-postgres.postgres.database.azure.com

  3. 测试私有终端节点：

    • 若使用私有终端节点，确认路由正确
    • 检查私有 DNS 区域

Ingress 问题

表现：

  • 从外部访问不了 LlamaCloud 界面
  • SSL 证书错误
  • 负载均衡器故障

解决办法：

  1. 检查 ingress 控制器：

    终端窗口

    kubectl get ingress
kubectl logs -n ingress-nginx deployment/nginx-ingress-controller

  2. 核实 DNS 配置：

    • 域名指向负载均衡器的 IP
    • SSL 证书有效

  3. 测试负载均衡器：

    终端窗口

    kubectl get svc -n ingress-nginx

性能问题

性能偏慢

常见原因：

  • 资源不足
  • 数据库性能问题
  • 网络延迟

解决办法：

  1. 查看资源用量：

    终端窗口

    kubectl top pods
kubectl top nodes

  2. 扩容资源：

    终端窗口

    kubectl scale deployment llamacloud --replicas=3 -n llamacloud

  3. 优化 Azure 服务：

    • 提高 PostgreSQL 的计算档位
    • 改用 Premium 档的 Redis
    • 为 Cosmos DB 启用自动伸缩

内存/CPU 问题

表现：

  • pod 重启
  • OOMKilled 事件
  • CPU 使用率偏高

解决办法：

  1. 检查资源上限：

    终端窗口

    kubectl describe pod <pod-name> -n llamacloud

  2. 在 values.yaml 里提高上限：

    backend:
  resources:
    limits:
      memory: 4Gi
      cpu: 2

错误码对照

常见 HTTP 错误

  • 500 Internal Server Error：查 backend 日志与数据库连通性
  • 502 Bad Gateway：确认 backend pod 是否在运行
  • 503 Service Unavailable：检查服务健康度与伸缩问题
  • 401 Unauthorized：OIDC 配置有问题
  • 403 Forbidden：Azure 服务的权限有问题

常见数据库错误

  • Connection refused：防火墙问题或网络问题
  • Authentication failed：凭据不对
  • SSL required：缺少 SSL 配置
  • Database does not exist：数据库名对不上

寻求帮助

收集诊断信息

在联系支持之前，先收集：

终端窗口

# Basic cluster info
kubectl -n llamacloud get pods -o wide
kubectl -n llamacloud get svc
kubectl -n llamacloud get secrets
kubectl -n llamacloud get configmaps

# Logs from all services
kubectl -n llamacloud logs deployment/llamacloud              > llamacloud.log
kubectl -n llamacloud logs deployment/llamacloud-layout       > llamacloud-layout.log
kubectl -n llamacloud logs deployment/llamacloud-ocr          > llamacloud-ocr.log
kubectl -n llamacloud logs deployment/llamacloud-operator     > llamacloud-operator.log
kubectl -n llamacloud logs deployment/llamacloud-temporal-parse        > llamacloud-temporal-parse.log
kubectl -n llamacloud logs deployment/llamacloud-telemetry    > llamacloud-telemetry.log
kubectl -n llamacloud logs deployment/llamacloud-web          > llamacloud-web.log
kubectl -n llamacloud logs deployment/temporal-jobs-worker    > temporal-jobs-worker.log
kubectl -n llamacloud logs deployment/llamacloud-s3proxy      > llamacloud-s3proxy.log

# Cluster events
kubectl get events --sort-by='.lastTimestamp' -n llamacloud

# Resource usage
kubectl top pods
kubectl top nodes

联系支持

  • LlamaCloud 支持：support@llamaindex.ai
  • 请附上：部署配置、错误日志、Azure 资源详情
  • 请勿提供：密钥、凭据或其他敏感数据

友情链接

  • Agents.md面向 AI 编码助手的仓库说明文件规范
  • LangChainLangChain 是一个开放的Agent平台
  • LangSmithAgent 工程平台：可观测与评估、部署、Fleet、Engine 等
  • EmbabelEmbabel 是一个JVM平台Agent框架
  • SpringAISpringAI 是一个基于 Spring 的 AI 框架
  • MCPModel Context Protocol，连接 AI 应用与外部数据/工具的开放标准
  • LangChain4jJava 生态的 LLM 应用开发框架
  • LlamaIndex把数据接入 LLM 的框架与文档平台
  • LlamaParse智能体式 OCR 文档解析：把 PDF、扫描件变成 LLM 可用的文本与结构化数据
  • LiteParse本地优先、轻量的文档解析库，不需要 API key
  • CrewAI多智能体编排框架：以 Crew/Flow 组织自主协作的 AI Agent
  • MAFMicrosoft Agent Framework，企业级 .NET/Python 智能体框架

BytesRouter 是社区翻译站点，所有译文仅供参考，一切以官方英文原文为准。

© 2026 BytesRouter · 译文采用 CC BY 4.0 许可