BytesRouter

主题

LlamaParse 文档版本 跟随上游 源快照 0a615984 更新于 2026-10-16

Files → Connections 页能做的一切，REST API 也都能做。本页以一个 S3 bucket 走完整条路径，从 access key 到跑起来的索引或批量任务：

  1. 用该 bucket 的 access key 创建一个连接。
  2. 让该连接订阅某个 bucket 与前缀。
  3. 创建一个文件夹（API 术语里叫 directory），并把订阅接进去。
  4. 启动首次同步。
  5. 在这个文件夹上建索引，或在其上跑批量任务。

每个请求都用你的 API key 作为 bearer token 认证。示例从 LLAMA_CLOUD_API_KEY 读取。EU 地域请把基础 URL 换成 https://api.cloud.eu.llamaindex.ai。

注意

Python SDK 目前还没有封装 connection 与 subscription 端点，因此 Python 示例用 httpx 直接调 REST API。索引与批量任务是有 SDK 方法的，见索引快速上手与 Batches。

用 API 创建 S3 连接

POST /api/v2/connectors 会保存这组 access key 对，并在入库前先向 AWS 校验。该 IAM 用户需要在 bucket 上具备 s3:ListBucket 与 s3:GetObject，如为 S3 连接器创建 IAM 用户所述。

  • Python
  • cURL
import os

import httpx

client = httpx.Client(
    base_url="https://api.cloud.llamaindex.ai",
    headers={"Authorization": f"Bearer {os.environ['LLAMA_CLOUD_API_KEY']}"},
    timeout=60,
)

connector = client.post(
    "/api/v2/connectors",
    json={
        "name": "Invoices bucket",
        "integration": "s3",
        "config": {
            "source_type": "s3",
            "auth_credentials": {
                "auth_type": "service_account",
                "aws_access_id": os.environ["AWS_ACCESS_KEY_ID"],
                "aws_access_secret": os.environ["AWS_SECRET_ACCESS_KEY"],
                # For an S3-compatible store, add its base URL:
                # "s3_endpoint_url": "https://s3-compatible.example.com",
            },
        },
    },
)
connector.raise_for_status()
connector_id = connector.json()["id"]
print("Connector:", connector_id)

后面的片段都基于这一段 —— 请按顺序把它们粘进同一个文件。

终端窗口

curl -sS -X POST "https://api.cloud.llamaindex.ai/api/v2/connectors" \
  -H "Authorization: Bearer $LLAMA_CLOUD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Invoices bucket",
    "integration": "s3",
    "config": {
      "source_type": "s3",
      "auth_credentials": {
        "auth_type": "service_account",
        "aws_access_id": "'"$AWS_ACCESS_KEY_ID"'",
        "aws_access_secret": "'"$AWS_SECRET_ACCESS_KEY"'"
      }
    }
  }'

把响应里的 id 存成 CONNECTOR_ID。

响应里绝不会带回 secret。除了 201，还可能返回：

状态码含义
409本 project 已有同一 AWS 身份的连接。请复用它，再加一条订阅即可。
422AWS 拒绝了这组 key 对，或缺少必填字段。detail 会说明是哪一项。
503无法连通 AWS。原样重试该请求。

让 S3 连接订阅某个 bucket

订阅说明「同步什么」：一个 bucket，可选收窄到某个前缀。LlamaCloud 在创建订阅前会先用该连接的 key 列举一次 bucket，所以 bucket 名拼错、或缺少 s3:ListBucket 权限会当场失败，而不是等到首次同步。

  • Python
  • cURL
subscription = client.post(
    f"/api/v2/connectors/{connector_id}/subscriptions",
    json={
        "scope_config": {
            "source_type": "s3",
            "bucket": "acme-documents",
            "prefix": "invoices/2024/",  # omit to sync the whole bucket
        },
    },
)
subscription.raise_for_status()
subscription_id = subscription.json()["id"]
print("Subscription:", subscription_id)

终端窗口

curl -sS -X POST "https://api.cloud.llamaindex.ai/api/v2/connectors/$CONNECTOR_ID/subscriptions" \
  -H "Authorization: Bearer $LLAMA_CLOUD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "scope_config": {
      "source_type": "s3",
      "bucket": "acme-documents",
      "prefix": "invoices/2024/"
    }
  }'

把响应里的 id 存成 SUBSCRIPTION_ID。

404 表示 bucket 不存在，403 表示这把 key 无权列举它，409 表示该连接已有针对同一 bucket 与前缀的订阅。

把 S3 订阅接进文件夹

文件会落在 directory 里，用两个调用把它和订阅接起来：

  • POST /api/v1/beta/directories 带上 connector_subscription_id，创建这个 directory 并标记为从该订阅同步。
  • POST /api/v1/beta/directories/ingest-configs 把订阅的文件路由进这个 directory。少了这一步，directory 存在但始终是空的。
  • Python
  • cURL
directory = client.post(
    "/api/v1/beta/directories",
    json={
        "name": "invoices-2024",
        "connector_subscription_id": subscription_id,
    },
)
directory.raise_for_status()
directory_id = directory.json()["id"]

ingest_config = client.post(
    "/api/v1/beta/directories/ingest-configs",
    json={
        "target_directory_id": directory_id,
        "source": {"type": "connector_subscription", "id": subscription_id},
    },
)
ingest_config.raise_for_status()
print("Directory:", directory_id)

终端窗口

curl -sS -X POST "https://api.cloud.llamaindex.ai/api/v1/beta/directories" \
  -H "Authorization: Bearer $LLAMA_CLOUD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "invoices-2024", "connector_subscription_id": "'"$SUBSCRIPTION_ID"'"}'

# Save the directory's id as DIRECTORY_ID, then:
curl -sS -X POST "https://api.cloud.llamaindex.ai/api/v1/beta/directories/ingest-configs" \
  -H "Authorization: Bearer $LLAMA_CLOUD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "target_directory_id": "'"$DIRECTORY_ID"'",
    "source": {"type": "connector_subscription", "id": "'"$SUBSCRIPTION_ID"'"}
  }'

ingest config 默认会镜像删除：bucket 里被删掉的对象，会在下次同步时从 directory 里移除。若希望在源头删除后仍保留文件，请传 "deletion_mode": "append_only"。

一个订阅只能喂给一个 directory。如果这两步里有任何一步失败，请先删掉前面已创建的东西再重试，否则该订阅会同步到一个空处，并且挡住同一 bucket 与前缀的新订阅。

启动并观察 S3 同步

新建的订阅大约各自每天同步一次。要立刻开始首次同步，就主动请求一次。该调用在同步入队后立即返回。

  • Python
  • cURL
import time

client.post(
    f"/api/v2/connectors/{connector_id}/subscriptions/{subscription_id}/sync"
).raise_for_status()

# Wait for the first sync to finish before indexing or batching the directory.
while True:
    subscriptions = client.get(
        f"/api/v2/connectors/{connector_id}/subscriptions"
    ).json()["items"]
    current = next(s for s in subscriptions if s["id"] == subscription_id)
    if current["status"] in ("invalid_auth", "invalid_scope") or current["last_error"]:
        raise RuntimeError(f"Sync failed: {current['status']} {current['last_error']}")
    if current["last_sync_at"] and current["status"] != "running":
        break
    time.sleep(10)

print("Synced at", current["last_sync_at"])

终端窗口

curl -sS -X POST \
  "https://api.cloud.llamaindex.ai/api/v2/connectors/$CONNECTOR_ID/subscriptions/$SUBSCRIPTION_ID/sync" \
  -H "Authorization: Bearer $LLAMA_CLOUD_API_KEY"

# Check progress: status, last_sync_at, last_error
curl -sS "https://api.cloud.llamaindex.ai/api/v2/connectors/$CONNECTOR_ID/subscriptions" \
  -H "Authorization: Bearer $LLAMA_CLOUD_API_KEY" \
  | jq --arg id "$SUBSCRIPTION_ID" '.items[] | select(.id == $id) | {status, last_sync_at, last_error}'

订阅的 status 是以下之一：

状态含义
idle当前没有同步。可查看 last_sync_at 与 last_error 了解上次结果。
running正在同步。
invalid_authaccess key 已失效。同步会暂停，直到更换连接。
invalid_scope该 bucket 或前缀已无法用这把 key 读取。同步会暂停。

要看同步来的文件，用 GET /api/v1/beta/directories/{directory_id}/files 列举该 directory。

在 S3 同步来的文件夹上建索引

基于该 directory 构建的索引，会对连接器同步进来的内容做解析与嵌入。把 sync_frequency 设为 daily，索引就会自行跟随连接器的变更而无需你手动触发同步；默认的 manual 只在你调用 POST /api/v1/indexes/{index_id}/sync 时才重新同步。

  • Python
  • cURL
index = client.post(
    "/api/v1/indexes",
    json={
        "name": "invoices-2024",
        "source_directory_id": directory_id,
        "sync_frequency": "daily",
    },
)
index.raise_for_status()
print("Index:", index.json()["id"])

终端窗口

curl -sS -X POST "https://api.cloud.llamaindex.ai/api/v1/indexes" \
  -H "Authorization: Bearer $LLAMA_CLOUD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "invoices-2024",
    "source_directory_id": "'"$DIRECTORY_ID"'",
    "sync_frequency": "daily"
  }'

检索、状态轮询与向量库选项与任何其他索引完全相同。见索引快速上手与同步。

在 S3 同步来的文件夹上跑批量任务

一个批量任务在 directory 的文件上运行同一种任务（例如 Parse 或 Extract 任务）。请等首次同步结束再创建，否则批量任务可能起始于一个还是空的 directory。

  • Python
  • cURL
batch = client.post(
    "/api/v2/batches",
    json={
        "source_directory_id": directory_id,
        "config": {
            "job": {
                "type": "parse_v2",
                "configuration_id": "cfg-PARSE_AGENTIC",
            },
        },
    },
)
batch.raise_for_status()
print("Batch:", batch.json()["id"], batch.json()["status"])

终端窗口

curl -sS -X POST "https://api.cloud.llamaindex.ai/api/v2/batches" \
  -H "Authorization: Bearer $LLAMA_CLOUD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "source_directory_id": "'"$DIRECTORY_ID"'",
    "config": {"job": {"type": "parse_v2", "configuration_id": "cfg-PARSE_AGENTIC"}}
  }'

如何观察批量任务并读取其结果，见 Batches。

用 API 停止同步或断开连接

请求对已同步文件的影响
DELETE /api/v2/connectors/{connector_id}/subscriptions/{subscription_id}保留。该 directory 不再接收变更。
DELETE /api/v2/connectors/{connector_id}保留。该连接下的每个订阅都被删除，其 directory 停止同步。
DELETE /api/v1/beta/directories/{directory_id}连同 directory 与其订阅一起删除。

从 S3 数据源迁到 S3 连接器

如果你之前是用较早的数据源 API 配的 S3，字段是能对上的：

数据源（CloudS3DataSource）连接器
aws_access_id、aws_access_secret、s3_endpoint_urlPOST /api/v2/connectors 上的 config.auth_credentials
bucket、prefixPOST /api/v2/connectors/{connector_id}/subscriptions 上的 scope_config
把数据源挂到 pipeline建一个索引或批量任务，并把 source_directory_id 指向该同步目录

凭据只需在连接里保存一次，所以一组 access key 就能喂给任意多个 bucket 的订阅，而每个同步目录也都可以支撑一个索引、一个批量任务，或两者都用。

友情链接

  • 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 许可