> ## Documentation Index
> Fetch the complete documentation index at: https://help.decodo.com/llms.txt
> Use this file to discover all available pages before exploring further.

# LlamaIndex

> 面向 LlamaIndex 的 Decodo 读取器和工具：将实时网页和搜索结果加载到 RAG 流程中，或让智能体抓取和搜索网络。

Decodo 的 LlamaIndex 集成以两个 Python 软件包的形式提供：

* **`llama-index-readers-decodo`**：读取器，可将网页和搜索结果加载为 LlamaIndex `Document` 对象，用于 RAG 流程
* **`llama-index-tools-decodo`**：工具集（tool spec），可让 LlamaIndex 智能体抓取 URL 并搜索 Google 和 Amazon

> [!NOTE]
>
> 源代码、示例和最新版本请查看 [**llama\_index 仓库**](https://github.com/Decodo/llama_index)。

## 要求

* Python 3.10 及以上版本
* Decodo [**Web Data API 计划**](https://dashboard.decodo.com/web-data/pricing)。[**控制面板**](https://dashboard.decodo.com/)提供免费试用。

## 安装

安装其中一个或两个软件包：

```bash theme={null}
pip install llama-index-readers-decodo llama-index-tools-decodo
```

## 身份验证

从 [**Web Data API 演练场**](https://dashboard.decodo.com/web-data/playground)复制您的 Web Data API 密钥，并将其存储在 `DECODO_API_TOKEN` 环境变量中。所有类都从该变量读取密钥：

```bash theme={null}
export DECODO_API_TOKEN=your_api_key
```

然后在创建每个类时传入 `auth_mode="token"`：

```python theme={null}
from llama_index.readers.decodo import DecodoWebReader

reader = DecodoWebReader(auth_mode="token")
```

> [!WARNING]
>
> `auth_mode` 的默认值是 `"basic"`，而不是 `"token"`。如果省略该参数，API 密钥会被当作基本身份验证令牌发送，每个请求都会失败并返回 `Username invalid.`

较旧的计划只有基本身份验证令牌（base64 编码的 `username:password`）。请将其放入 `DECODO_API_TOKEN` 并省略 `auth_mode`，因为 `"basic"` 就是默认值。您也可以使用 `api_token=` 直接传入凭据，而不使用环境变量。

## 为 RAG 加载网页

`DecodoWebReader` 会抓取每个 URL，并以 Markdown 格式将页面作为 `Document` 返回。以下示例会索引两个页面并进行查询。它使用 LlamaIndex 默认的 OpenAI 模型，因此还需要 `llama-index-llms-openai`、`llama-index-embeddings-openai` 和一个 `OPENAI_API_KEY`：

```python theme={null}
# main.py
from llama_index.core import VectorStoreIndex
from llama_index.readers.decodo import DecodoWebReader

reader = DecodoWebReader(auth_mode="token")
documents = reader.load_data(
    [
        "https://quotes.toscrape.com",
        "https://quotes.toscrape.com/page/2/",
    ]
)

# Drop pages that failed to scrape before indexing them
documents = [doc for doc in documents if "error" not in doc.metadata]

index = VectorStoreIndex.from_documents(documents)
query_engine = index.as_query_engine()

print(query_engine.query("Which quotes are about books or reading?"))
```

每个 `Document` 的 metadata 中都包含 `url`、`source` 和 `status_code`。URL 会按顺序逐个抓取。

> [!WARNING]
>
> 抓取失败的 URL 默认不会抛出异常。它仍会返回一个 `Document`，错误信息会作为该文档的**正文**（`[Decodo scrape error] ...`），并在 metadata 中带有 `error` 键。请像上面的示例那样将它们过滤掉，否则错误文本会和您的页面一起被索引。若要在首次失败时抛出异常，请向 `load_data()` 传入 `continue_on_error=False`。

## 加载搜索结果

`DecodoSearchReader` 会运行一次搜索，并以 Markdown 格式返回结果页面：

```python theme={null}
from llama_index.readers.decodo import DecodoSearchReader

reader = DecodoSearchReader(auth_mode="token")
documents = reader.load_data("wireless keyboard", engine="amazon")
```

| 参数 | 默认值 | 说明 |
| - | - | - |
| `query` | – | 搜索查询。必填 |
| `engine` | `"google"` | `"google"` 调用 `google_search` 目标，`"amazon"` 调用 `amazon_search` |
| `num_results` | `10` | 以 `limit` 的形式发送给 API |

每次搜索只返回**一个** `Document`，其中包含整个结果页面，而不是每条结果一个 `Document`。其 metadata 包含 `query`、`engine`、`target`、`url`、`source` 和 `status_code`。如果搜索失败，该读取器会抛出 `RuntimeError`。

> [!NOTE]
>
> `num_results` 并不会限制返回的结果数量。Google 搜索始终会返回完整的第一页结果。

## 智能体工具

`DecodoToolSpec` 为 LlamaIndex 智能体提供抓取和搜索网络的工具。以下示例通过 `llama-index-llms-openai` 使用 OpenAI，但 LlamaIndex 支持的任何 LLM 均可使用：

```bash theme={null}
pip install llama-index-tools-decodo llama-index-llms-openai
export OPENAI_API_KEY=your_openai_key
```

```python theme={null}
# agent.py
import asyncio

from llama_index.core.agent.workflow import FunctionAgent
from llama_index.llms.openai import OpenAI
from llama_index.tools.decodo import DecodoToolSpec

tools = DecodoToolSpec(auth_mode="token").to_tool_list()

agent = FunctionAgent(
    tools=tools,
    llm=OpenAI(model="gpt-5-mini"),
)


async def main():
    response = await agent.run(
        "Search Google for the 2025 NBA Finals, scrape the Wikipedia page about it and tell me who won."
    )
    print(response)


asyncio.run(main())
```

`to_tool_list()` 会为智能体提供以下工具：

| 工具 | 用途 | 返回内容 |
| - | - | - |
| `scrape_url` | 抓取任何 URL | 以 Markdown 格式返回页面 |
| `search_web` | Google 搜索 | 结果列表，每条包含 `url`、`content` 和 `status_code` |
| `search_amazon` | Amazon 搜索 | 结果列表，每条包含 `url`、`content` 和 `status_code` |

两个搜索工具都会在 `content` 中以 Markdown 格式返回结果页面，并在搜索失败时抛出 `RuntimeError`，以便智能体重试。

## 配置

`DecodoWebReader`、`DecodoSearchReader` 和 `DecodoToolSpec` 接受相同的参数：

| 参数 | 默认值 | 说明 |
| - | - | - |
| `api_token` | `DECODO_API_TOKEN` | API 密钥，或较旧计划的基本身份验证令牌 |
| `auth_mode` | `"basic"` | 使用 API 密钥时设置为 `"token"` |
| `timeout` | `180` | 请求超时秒数 |

完整的 API 参数列表请参阅[**参数**](https://help.decodo.com/docs/web-scraping-api-parameters-overview.md)。

***

## 相关内容

* [**LangChain（Python）**](https://help.decodo.com/docs/cn/langchain-python.md)：面向 LangChain 的 Decodo 工具和文档加载器。
* [**CrewAI**](https://help.decodo.com/docs/cn/crewai.md)：面向 CrewAI 智能体和团队的 Decodo 工具。
* [**Python SDK**](https://help.decodo.com/docs/cn/python-sdk.md)：在 Python 中以类型化方式访问所有 Decodo 目标。
* [**MCP 服务器**](https://help.decodo.com/docs/cn/mcp.md)：将 AI 智能体和兼容 MCP 的工具连接到 Decodo。
* [GitHub 仓库](https://github.com/Decodo/llama_index)：查看源代码、示例和最新版本。

***

> [card] [支持](https://direct.lc.chat/12092754)
>
> 需要帮助或只是想打个招呼？我们的支持团队全天候为您服务。 \
> 您也可以随时通过电子邮件 [support@decodo.com](mailto:support@decodo.com) 联系我们。

> [card] [反馈](mailto:feedback@decodo.com)
>
> 找不到您要找的内容？请求一篇文章！ \
> 有反馈意见？分享您对我们如何改进的想法。


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.