BytesRouter

主题

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

LlamaCloud 的 Index 资源通过一条同步流水线把源目录绑到一个向量库上。默认的目的向量库 —— 即 index target —— 是在部署级别通过 backend、jobs 与 Temporal worker pod 上的环境变量来配置的。

Index target 的存储与平台自身的元数据库（Postgres 与 MongoDB，见Databases and Queues）是分开配置的。两者角色不同：平台库存用户、project 与任务；index target 存嵌入与分块。把两者分开，你就能挑一个面向向量优化的目的地，而不必把它与部署的其他部分绑在一起。

支持的向量库导出

目标何时使用
MongoDB已在使用 MongoDB，并希望顺带用上 Search 能力。Atlas（8.1+）以及跑着 MongoDB Search / mongot 的自管部署（8.2+）都支持。
Turbopuffer大规模向量负载；按 namespace 做租户隔离
PostgreSQL (pgvector)不需要额外的向量基础设施 —— 可复用平台的 Postgres（或单独一个）；是无外部存储（minimal profile）部署的默认目标
Azure AI Search已在 Azure 上；想要原生混合检索；需要带类型的可过滤元数据
Custom你要的向量库没有原生集成？我们鼓励用户直接读取同步产出的解析结果、自己编写导出逻辑。多个自定义方案的样例见我们的示例仓库。

部署级默认值决定的是新索引的后端类型。改动它不会改变已有 Index 的后端类型，重新同步也一样。

新索引默认落到哪个目的地，由 Helm values 里的 config.defaultIndex.destination 决定（环境变量 DEFAULT_DIRECTORY_INDEX_DESTINATION；取值之一为 mongodb、turbopuffer、postgres、azureai_search）。不设时，新索引默认用 mongodb —— 或在禁用了 MongoDB 的部署上用 postgres。

改动某个后端的连接设置后，等新配置被加载，已有索引就可能指向同一类型下的另一个库。此后重新同步会从该 Index 当前的输出里导出缺失或已变更的数据，但它不会从旧库拷贝数据，也不会清理旧库。

MongoDB

两种部署形态都能跑：

  • MongoDB Atlas —— Search 与 Vector Search 内建。
  • 自管 MongoDB（Community 或 Enterprise）—— 需要 MongoDB Search，即与 mongod 并行运行的独立 mongot 进程。

最低版本

部署形态MongoDB 最低版本附加要求
Atlas8.1集群上已启用 Search / Vector Search
Self-managed8.2已部署 mongot 并挂到该副本集上

集群要求

要求为何需要
网络可达性backend、jobs 与 Temporal worker 的 pod 都会发起连接。在 Atlas 上，把集群的出口地址加入 IP 访问列表，或用 PrivateLink / VPC peering 前置集群；自管的话，要确保 pod 同时能连到 mongod 与 mongot 节点。
一个专用的数据库LlamaCloud 会在这里创建并写入一个集合及其索引。不要把它指向平台自己的 MongoDB 数据库。

在 Atlas 上，为集群定规格时请查 Atlas Search 文档 里各档位的 search index 上限。

自管部署

mongot 有一批与 LlamaCloud 无关的部署约束：它挂到一个已运行、已开启认证的副本集上，无法对着单机或空集群启动；而且每个 mongot 组只绑一个副本集，不能在多个副本集之间共享。常见的生产形态是三个 mongod 成员配两个 mongot 节点；开发环境用一台把两者放在同一台机器上也足够。规模与拓扑建议见 MongoDB 的自管 Search 文档。

用到的 Search 能力

两种部署都必须提供下列能力。若要核对某项具体能力，MongoDB 有 Atlas 与自管 Search 之间的特性兼容性文档。

能力用在哪里
createSearchIndexes, listSearchIndexes首次导出时创建 search index，并检查它是否已存在
$rankFusion检索 —— 把向量与全文两条流水线融合起来。由 mongod 而非 mongot 提供，因此取决于服务端版本而不是 Search
$search两条检索流水线都会用：向量那一腿用 vectorSearch 算子，全文那一腿用 compound
knnVector field typesearch index 定义里的 embedding 字段

连接

变量说明
DEFAULT_INDEX_MONGO_URI完整的 SRV 或标准连接 URI（例如 mongodb+srv://...）
DEFAULT_INDEX_MONGO_DB数据库名
DEFAULT_INDEX_MONGO_COLLECTION集合名（所有索引数据共用这一个集合）

三者必须一起提供。在 Helm values 里它们由 config.defaultIndex.mongo.* 渲染出来：

config:
  defaultIndex:
    destination: mongodb
    mongo:
      uri: "mongodb+srv://<user>:<password>@<cluster>.mongodb.net/?retryWrites=true&w=majority"
      db: "llamacloud_index"
      collection: "index_chunks"

只设其中一部分会让 chart 渲染失败并报 config.defaultIndex.mongo requires uri, db, and collection to all be set。要改从一个已存在的 Kubernetes secret 里取值而不是内联，就把 config.defaultIndex.secret 设成它的名字并省掉 mongo 块 —— 此时该 secret 必须自己提供全部三个 DEFAULT_INDEX_MONGO_* 键。

这个 URI 会被当作机密对待，与平台的 MONGODB_URL 一起存进渲染出的 default-index-secret。请把它与平台自己的 MongoDB 连接区分开：用不同的集群，或至少用不同的数据库。

数据库用户权限

LlamaCloud 会在首次使用时以程序方式创建集合、普通索引与 search index。因此数据库用户需要两个内建角色，且作用范围限定在目标数据库上：

  • readWrite —— 覆盖 insert、delete、find、aggregate（含 $search 与 $rankFusion）、createCollection、listCollections、listIndexes 以及创建普通索引。
  • dbAdmin —— 覆盖 search index 的 createSearchIndexes 与 listSearchIndexes 命令，这两个不在 readWrite 里。

只有 readWrite 是不够的：同步流程在首次导出、试图创建 search index 时会因权限错误失败。平台从不删除索引或集合，因此不需要 dropSearchIndex 与 dropCollection。若安全评审要求更紧的授权，用一个自定义角色授予 readWrite 的动作再只加上 createSearchIndexes 与 listSearchIndexes 即可。在 Atlas 上参见自定义角色。

LlamaCloud 会创建什么

首次向某个数据库导出时，LlamaCloud 会按需创建下列对象（前提是该用户持有上面的角色），无需事先建好任何东西。

对象名称用途
Collectionyour DEFAULT_INDEX_MONGO_COLLECTION存放该部署中所有索引的分块、元数据与嵌入
Regular indexix_export_config_file建立在 (export_config_id, parsed_directory_file_id) 上的复合索引；增量同步的比对靠它列出哪些文件已导出
Search indexsearch_index_v1一个 search 类型的索引，同时承载全文映射与向量映射

search index 把 content 映射给全文检索；把 _id、tenant_id、export_config_id 与 parsed_directory_file_id 作为用于过滤的 token；把 metadata_fields 作为动态文档，使任意分块元数据都可过滤；把 embedding 作为余弦相似度的向量字段并使用标量量化。

由此带来两点：

  • search index 的构建是异步的。 LlamaCloud 发出 createSearchIndexes 后继续往下走，不会阻塞到索引可查询。首次同步时，检索可能在部署建索引所需的一两分钟内返回空结果，尽管导出本身已成功。这时请重试查询，而不是重跑同步。
  • 更换嵌入模型必须新建索引。 向量维度来自所配置的嵌入模型并在索引定义里固定，因此换模型意味着新的 search index 加一次完整重同步。见下文嵌入模型。

数据布局与租户隔离

该部署中的所有索引共用一个集合。隔离是基于过滤而非物理的：每个文档都带 tenant_id（即 project）与 export_config_id（即索引），且每条检索查询都会在用户自带的过滤条件之前把这两者钉成 must 子句。若你需要按租户做物理隔离，请用 Turbopuffer —— 它为每个索引分配一个 namespace。

每个分块作为一个文档存储，含其文本、嵌入、页与字符偏移，以及摊平在 metadata_fields 下的自定义元数据。重新同步一个文件会先删掉它已有的分块再重新插入，因此两次解析之间分块数量变化也不会留下孤儿。从源目录删除文件时，若索引的删除模式是 mirror，其分块会被移除；append_only 则原地保留。

验证与排障

用 configz 端点确认目的地已接通。它只校验环境变量是否存在且可解析，从不连接集群，所以即便状态是 CONFIGURED，同步时仍可能连接失败。

症状原因处理
503 on retrieval, with MongoDB index V2 is not configured for this environmentpod 上缺失三个 DEFAULT_INDEX_MONGO_* 变量中的一个或多个补上缺失的变量 —— 报错信息会点名它们
Sync fails on its first export with a privilege error数据库用户无法执行 createSearchIndexes在 readWrite 之外授予 dbAdmin，或等价的自定义角色 —— 见上文「数据库用户权限」
Retrieval fails with an unrecognized-stage error naming $rankFusion服务端版本低于 8.1升级部署以满足上文「最低版本」
Retrieval fails with an unrecognized-stage error naming $search该部署没有 Search —— mongot 没在跑，或 Atlas 集群上未启用 Search部署 mongot，或在集群上启用 Search
Retrieval returns zero results immediately after a first sync, though the sync succeededsearch index 仍在构建 —— 创建命令在索引可查询之前就返回了重试查询；不要重跑同步

Turbopuffer

需要一个 Turbopuffer 账号与 API key。每个 Index 会拿到一个由 Index ID 派生出的专属 Turbopuffer namespace，因此一个 Turbopuffer 账号就能扩展到任意多的索引，而无需按索引准备基础设施。

变量说明
DEFAULT_INDEX_TPUF_API_KEYTurbopuffer 的 API key
DEFAULT_INDEX_TPUF_REGION新 namespace 所在地域（默认 aws-us-east-1）
DEFAULT_INDEX_TPUF_NAMESPACE_PREFIX加在每个 namespace 名前的前缀（默认 llamacloud）—— 最终的 namespace 为 {prefix}-{index_id}

PostgreSQL (pgvector)

用 pgvector 扩展把分块与嵌入存进 PostgreSQL —— 不需要额外的向量基础设施。这是无外部存储（minimal profile）部署的默认目标，连接可以指向平台自己的 Postgres，也可以是专门的库。

变量说明
DEFAULT_INDEX_PG_HOSTPostgreSQL 主机
DEFAULT_INDEX_PG_PORT端口（默认 5432）
DEFAULT_INDEX_PG_NAME数据库名
DEFAULT_INDEX_PG_USER用户名
DEFAULT_INDEX_PG_PASSWORD密码

在 Helm values 里它们由 config.defaultIndex.postgres.{host,port,database,username,password} 渲染。留空的字段会继承对应的内联 postgresql.* 值，因此把平台 Postgres 凭据内联传入的部署（含 minimal profile）无需额外配置。若平台 Postgres 是通过已有 secret 提供（postgresql.secret），就要显式设 config.defaultIndex.postgres.* 各字段，或提供 config.defaultIndex.secret。

要求与行为：

  • 服务端必须可用 pgvector 扩展。LlamaCloud 会在首次导出时执行 CREATE EXTENSION IF NOT EXISTS vector。pgvector 不属于 受信任扩展，因此创建它通常需要超级用户级权限 —— 在托管服务上按常规机制走（Amazon RDS 的 master 用户 / rds_superuser、Azure 的 azure.extensions 允许清单、Cloud SQL 支持的扩展流程）。若 LlamaCloud 的数据库用户没有建扩展的权限，就由管理员一次性预先创建（CREATE EXTENSION vector;）—— 应用里的 CREATE EXTENSION IF NOT EXISTS 之后就是空操作。
  • 每种嵌入模型建一张表，命名为 index_v2_<embedding-model>，并在嵌入列上建 HNSW 索引。分块文本与元数据与向量同处一行。
  • 表内的租户隔离基于过滤（按 export config / tenant id），与其他托管目标一致。

需要一个启用了向量检索的 Azure AI Search 服务。LlamaCloud 会在首次同步时按 (export config, 嵌入模型) 各创建一个索引。

变量说明
DEFAULT_INDEX_AZUREAI_SEARCH_ENDPOINT服务端点，例如 https://<service>.search.windows.net
DEFAULT_INDEX_AZUREAI_SEARCH_AUTHENTICATION_CONFIGURATIONJSON 格式的认证配置；用 API key 认证时为 {"type": "api_key", "api_key": "<admin-key>"}。该 key 必须被允许创建索引。
DEFAULT_INDEX_AZUREAI_SEARCH_INDEX_NAME_PREFIX所建索引名的可选前缀（默认 llamacloud）

任意的分块元数据会被写进索引上一个带类型的 metadata 复杂集合，每个键一条：val_s（字符串，为大小写不敏感的相等比较做了小写归一）、val_n（double）、val_b（布尔）与 val_d（datetime —— 当字符串能按 ISO 8601 解析时填充）。list[str] 值会展开为每项一条。这些字段只能用于过滤 —— Azure 不支持跨复杂集合子字段做 $orderby 或分面关联 —— 因此请用 OData 的 any() 表达式来查：

$filter=metadata/any(m: m/key eq 'department' and m/val_s eq 'legal')
$filter=metadata/any(m: m/key eq 'created_at' and m/val_d ge 2026-01-01T00:00:00Z)

Azure 对每个文档的复杂集合元素上限是 3000，超出部分在写入时被静默丢弃。给已有索引新增一个顶层字段是无缝的（已有文档在该字段上读到 null），但更改已有字段的类型或其 filterable/sortable/facetable 属性就需要删除并重建索引 —— 即一次完整重同步。

重排序

索引检索可以可选地对向量 top-K 结果再跑一次重排。重排默认开启，且当配置了 Cohere 的 key 时使用 rerank-v3.5。要完全关闭重排（例如没有 Cohere 或 Bifrost 访问的部署）：

变量说明
RERANK_ENABLED设为 false 可全局关闭重排。默认为 true。

Cohere

变量说明
COHERE_PRIVATE_KEYCohere 的 API key
COHERE_RERANK_LANGUAGE取 multi、en、foreign 之一。默认为 multi。

网关（可选）

如果你已部署了 Bifrost 或 Portkey 这类 LLM 网关，可以让重排走网关，而不必直接调用 Cohere。这对集中管理凭据或按租户分流很有用。

变量说明
RERANK_GATEWAY_ENABLED设为 true 则让重排走网关
RERANK_GATEWAY用于归因请求头的网关：bifrost（默认）或 portkey
RERANK_GATEWAY_BASE_URL网关的基础 URL
RERANK_GATEWAY_DEFAULT_MODEL提供方/模型串（默认 cohere/rerank-v3.5）
RERANK_GATEWAY_DEFAULT_TOP_N默认返回多少条结果（默认 10）
RERANK_GATEWAY_TIMEOUT_SECONDS请求超时秒数（默认 30）
COHERE_PRIVATE_KEYCohere SDK 会以 Authorization: Bearer 发送的凭据。即便网关是用自定义请求头认证的，构造 client 时它仍然必需（用不上就填一个占位值）。

当网关与直连 Cohere 都配置了时，以网关为准。

旧的 BIFROST_RERANK_* 变量仍作为别名受支持。若某字段两种名字都设了，则对应的 RERANK_GATEWAY* 变量优先。

用自定义请求头认证的网关（例如 Portkey）

有些网关不接受用 Authorization: Bearer 做网关认证，而要求一个自定义请求头（Portkey 用 x-portkey-api-key）。只发 SDK 的 bearer token 会让网关把那个 key 继续往上游转发，结果是来自提供方（例如 Cohere）的 401。

重排复用共享的 LLM_HEADERS 设置（与聊天/嵌入的网关认证是同一套机制）。把网关的认证请求头设在那里，它就会连同可观测性请求头一起附加到每一次 rerank 请求上：

LLM_HEADERS_ENABLED=true
LLM_HEADERS={"x-portkey-api-key": "<portkey-api-key>"}

例如，要让托管在 Bedrock 上的 Cohere 模型经 Portkey 做重排：

RERANK_GATEWAY_ENABLED=true
RERANK_GATEWAY=portkey
RERANK_GATEWAY_BASE_URL=https://<your-portkey-host>/v1
RERANK_GATEWAY_DEFAULT_MODEL=@bedrock-uswest2/cohere.rerank-v3-5
COHERE_PRIVATE_KEY=<placeholder-or-unused>
LLM_HEADERS_ENABLED=true
LLM_HEADERS={"x-portkey-api-key": "<portkey-api-key>"}

嵌入与聊天 LLM

索引的同步与检索还需要：

  • 一个嵌入模型，在同步时把分块转成向量
  • 一个聊天 LLM，在查询时基于索引回答问题

两者都通过 LlamaCloud 的集中式 LLM 配置来解析。完整设置见集中式提供方配置。只要在 Helm values 的 config.llms.* 下配好对应的提供方，或通过 config.llms.providerConfigs 注册以获得更细的控制，相关模型就能立即用于 Index 操作。

嵌入模型

嵌入模型是写死为 openai-text-embedding-3-small 的。它不能按索引覆盖，也没有自动回退到其他模型的机制。

  • 若集中式 LLM 配置里注册了 openai-text-embedding-3-small，同步可用。
  • 若没有，同步会在工作流运行期以 EmbeddingConfigNotFoundError 失败。不会回退到任何其他模型。

这意味着运维者必须二选一：

  1. 直接配置 OpenAI 提供方（config.llms.openAi.apiKey），这会自动注册两个嵌入模型；或
  2. 通过 providerConfigs 显式注册 openai-text-embedding-3-small —— 当你要走网关或非 OpenAI 托管的端点时需要（见下文自定义端点）。

聊天 LLM

聊天智能体优先使用 OpenAI 的 GPT-5 系列模型，顺序如下：

  1. openai-gpt-5-4
  2. openai-gpt-5-4-mini
  3. openai-gpt-5-2
  4. openai-gpt-5
  5. openai-gpt-5-mini

取列表里第一个可用的模型。若一个都没有注册，解析器会回退到集中式配置里的任意其他 LLM（按优先级匹配）。若集中式配置里连一个能聊天的 LLM 都没有，聊天端点会返回 status=UNAVAILABLE，并附带说明未注册任何聊天 LLM 的消息。

请注意：

  • 聊天智能体目前使用 OpenAI 的原生 client，因此通过 providerConfigs 注册的非 OpenAI 模型必须由一个 OpenAI 兼容端点来服务（见自定义端点）。
  • 创建索引不会校验聊天 LLM 是否可用 —— 失败只在你发送聊天消息时才暴露。

自定义端点（OpenAI 兼容网关）

providerConfigs 里的每个提供方都支持 credentials.base_url 字段。这使得你可以把 LlamaCloud 指向 LiteLLM、Ollama、Azure AI Foundry 代理或任何其他 OpenAI 兼容端点，同时继续沿用 OpenAI 的模型标识（openai-gpt-5-4、openai-text-embedding-3-small 等）：

config:
  llms:
    providerConfigs:
      - id: "embedding-via-litellm"
        provider: "openai"
        model_id: "openai-text-embedding-3-small"
        enabled: true
        priority: 200
        credentials:
          api_key: "sk-litellm-..."
          base_url: "https://litellm.example.com/v1"
      - id: "chat-via-litellm"
        provider: "openai"
        model_id: "openai-gpt-5-4"
        enabled: true
        priority: 200
        credentials:
          api_key: "sk-litellm-..."
          base_url: "https://litellm.example.com/v1"

同样的 base-url 覆盖对 anthropic 与 gemini 提供方也生效（设在它们各自的 credentials 块里）。Azure 则使用独立的 credentials.endpoint 字段 —— 各提供方的完整凭据 schema 见集中式提供方配置。

验证配置

应用你的 Helm values 之后，访问 configz 端点确认每个目标都已正确配置：

终端窗口

curl -H "Authorization: Bearer $TOKEN" \
     -H "Project-Id: $PROJECT_ID" \
     https://<your-llamacloud-host>/api/v1/indexes/configz

响应会列出有哪些向量目标、嵌入模型、聊天 LLM 与重排器可用。环境变量缺失或非法的目标会显示为未配置。

友情链接

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