第 1 课

安装 SDK：Cloud 建树索引与 chat 问答

按官方 Getting Started：pip install、环境变量、PageIndexClient(index=cloud)、submit_document、client.chat。

图文22 分钟

课程目录第 1 / 2 课

学习位置仅保存在当前浏览器，有效期 180 天。

来源：PageIndex · Getting Started、SKILL.md、Client Configuration。本课走 Cloud 索引（index="cloud"）：由 PageIndex 负责解析 / OCR / 存储；问答模型始终是你自己的 LLM（chat=）。

你将得到什么

本机可运行的 pageindex Python 包
一份已写入 PageIndex Cloud 的 PDF，拿到可复用的 doc_id
一次成功的 client.chat(...) 流式或非流式回答（对照：终端出现完整答案文本）

开始前准备

Python 3.10+，可用 python3 --version 核对。
打开 PageIndex Developer Dashboard 生成 API Key（Cloud 索引必需）。
准备任一 LLM Key：本讲义示例用 OpenAI；官方亦支持 Anthropic / OpenRouter / OpenAI-compatible（见 Client 文档）。
准备一份 PDF（示例路径 ./2023-annual-report.pdf；换成你自己的文件即可）。扫描件 / 图表多的文档更适合 Cloud（官方对比：Local 只读文本层）。

核心事实（先记住）

项	官方值
安装	`pip install -U pageindex`
Cloud 索引 Key	环境变量 `PAGEINDEX_API_KEY`
问答 / Local 索引 Key	你的 LLM Key，如 `OPENAI_API_KEY`
Cloud 客户端	`PageIndexClient(index="cloud", chat="gpt-5.6-sol")`
提交文档	`client.submit_document(path, wait=True)["doc_id"]`
提问	`client.chat(query, doc_id=doc_id)` 或 `stream=True`
Agent 捷径	对 Claude Code / Cursor 粘贴：`Read https://docs.pageindex.ai/SKILL.md and follow it to set up PageIndex in this project.`

模型名遵循 LiteLLM 约定（官方 Client 页）：OpenAI 用裸名（示例 gpt-5.6-sol）；Anthropic 用 anthropic/...；OpenRouter 用 openrouter/...。

步骤 1：安装 SDK

pip install -U pageindex

对照结果：无报错结束；可再执行：

python3 -c "import pageindex; print(pageindex.__name__)"

应输出 pageindex。

步骤 2：配置环境变量

不要把 Key 写进源码或提交到 Git。

export PAGEINDEX_API_KEY="your-pageindex-key"
export OPENAI_API_KEY="your-openai-key"

把占位符换成 Dashboard / 提供商控制台里的真实值。若用 Anthropic：

export ANTHROPIC_API_KEY="your-anthropic-api-key"

对应客户端见步骤 3 的 Anthropic 示例。

步骤 3：创建 Client（Cloud）

按官方 Getting Started / Client：

from pageindex import PageIndexClient

client = PageIndexClient(
    index="cloud",       # 索引与存储在 PageIndex Cloud
    chat="gpt-5.6-sol",  # 仍由你自己的模型作答
)

Anthropic 示例（官方 Client「Use different LLMs」）：

client = PageIndexClient(
    index="cloud",
    chat="anthropic/claude-opus-5",
)

对照结果：创建对象无抛异常即可；真正校验在下一步提交文档。

（可选 Local 模式：不需要 PAGEINDEX_API_KEY，例如 PageIndexClient(index="gpt-5.6-luna", chat="gpt-5.6-sol")，只适合文本层 PDF；本课主线仍用 Cloud。）

步骤 4：提交 PDF 建树索引

把 ./2023-annual-report.pdf 换成你的路径：

# wait=True blocks until queryable
doc_id = client.submit_document("./2023-annual-report.pdf", wait=True)["doc_id"]
print(doc_id)

对照结果：打印出一个非空 doc_id 字符串。官方强调：Cloud 按页计费一次，请持久化并复用 doc_id，不要对同一文件反复 submit_document。

若不传 wait=True，需自行轮询：

doc_id = client.submit_document("./2023-annual-report.pdf")["doc_id"]
print(client.get_document(doc_id)["status"])  # 完成后为 "completed"

已有索引可列表：

print(client.list_documents())

步骤 5：对文档提问

非流式：

answer = client.chat("What are the key findings in this document?", doc_id=doc_id)
print(answer)

流式（官方 Getting Started）：

query = "What are the key findings in this document?"
for chunk in client.chat(query, doc_id=doc_id, stream=True):
    print(chunk, end="", flush=True)
print()

作用域（官方 SKILL）：doc_id 可为单个字符串、字符串列表；Cloud 还可用 folder_id=；都不传则搜整个库。

需要引用时加 citations=True（云文档可带 block 级 cite；细节见官方 LLM Integration / SKILL）。

对照结果：终端出现与 PDF 内容相关的回答文本；流式模式下内容分段刷出。若报鉴权错误，回到步骤 2 检查两个环境变量是否在同一 shell 生效（echo $PAGEINDEX_API_KEY | wc -c 应大于 1）。

本课检查清单

pip install -U pageindex 成功
Cloud Client 创建成功
拿到可复用的 doc_id
client.chat 返回可读答案

下一课：在已索引文档的前提下，把 https://api.pageindex.ai/mcp 接到 Claude Code / Cursor。