如何在LlamaIndex代理中处理Cloudflare Turnstile
Ethan Collins
Pattern Recognition Specialist
TL;DR
- 使用 LlamaIndex 的
FunctionTool.from_defaults()将窄范围的 CapSolver Turnstile 功能封装起来。 - 使用经过文档说明的
AntiTurnstileTaskProxyLess任务，并使用精确的页面 URL 和站点密钥。 - 仅在授权页面暴露这些可选值时发送
action和cdata。 - 将解决方案令牌返回给确定性的浏览器代码，而不是存储在长期代理内存中。
- 在生产前添加经过批准的主机验证、一次有限重试、日志脱敏和人工审核分支。
引言
在 LlamaIndex 代理中解决 Cloudflare Turnstile 最安全的方法是将 CapSolver 作为类型化的函数工具暴露出来，同时将浏览器状态、秘密和授权检查保留在模型之外。LlamaIndex 可以决定支持的挑战是否会阻止下一步的批准操作，但确定性的 Python 应该验证目标，构建经过文档说明的 AntiTurnstileTaskProxyLess，并将一个短期解决方案令牌返回给浏览器控制器。这遵循了 CapSolver AI 代理架构：模型决定，工具适配器定义动作，核心求解层执行它。本指南展示了具体的 Turnstile 字段、LlamaIndex FunctionTool 实现、FunctionAgent 工作流、安全令牌交接、有限重试和负责使用的控制措施，适用于 QA、RPA 和允许的浏览器自动化。
为什么 LlamaIndex FunctionTool 是一个好选择
LlamaIndex 将工具视为面向代理的 API。其 官方工具文档 解释了 FunctionTool 可以封装同步或异步 Python 函数，并从函数签名中推断出模式。工具名称、描述、注释和文档字符串会影响模型调用它的时机。
这种边界对于挑战恢复很有用，因为模型永远不应该生成任意的求解代码或接收 CapSolver API 密钥。一个窄范围的函数只能接受经过批准的页面 URL、Turnstile 站点密钥和可选的 widget 元数据。
CapSolver AI 博客 涵盖了代理集成，而 CapSolver AI 和自动化 FAQ 解释了挑战恢复如何补充现有的代理堆栈。
理解官方的 Turnstile 任务
CapSolver 的 Cloudflare Turnstile 文档 指定了 AntiTurnstileTaskProxyLess。该任务需要 websiteURL 和 websiteKey。可选的元数据可以包括 widget 的 action 和 cdata 值。
| 字段 | 必需 | 来源 | 目的 |
|---|---|---|---|
type |
是 | 固定 | AntiTurnstileTaskProxyLess |
websiteURL |
是 | 经批准的当前页面 | 将解决方案与页面关联 |
websiteKey |
是 | Turnstile widget | 识别 widget 配置 |
metadata.action |
否 | data-action |
保留 widget 的动作值 |
metadata.cdata |
否 | data-cdata |
保留 widget 使用的客户数据 |
CapSolver 自动支持托管的、非交互的和不可见的 Turnstile 表现形式，因此任务不需要子类型。Cloudflare 的 Turnstile 文档 描述了 widget 和站点所有者使用的服务器端验证过程。
安装 LlamaIndex 和 CapSolver
bash
pip install llama-index llama-index-llms-openai capsolver对于用户文档中提供的更广泛的 CapSolver 代理架构，还需安装核心和代理包：
bash
pip install git+https://github.com/capsolver-ai/capsolver-core.git
pip install git+https://github.com/capsolver-ai/capsolver-agent.git将秘密配置在提示之外：
bash
export CAPSOLVER_API_KEY="CAP-xxxxxxxxxxxxxxxx"
export OPENAI_API_KEY="sk-xxxxxxxxxxxxxxxx"下面的直接 SDK 示例使用了精确的 Turnstile 任务字段。LlamaIndex 提供框架外壳；CapSolver 执行任务。
创建类型化的 Turnstile 函数
在将 URL 发送到 CapSolver 之前进行验证。模型不应该能够选择任意的主机名。
python
import os
from typing import Annotated
from urllib.parse import urlparse
import capsolver
capsolver.api_key = os.environ["CAPSOLVER_API_KEY"]
ALLOWED_HOSTS = {
"staging.example.com",
"qa.example.com",
}
def solve_turnstile(
website_url: Annotated[str, "包含 Turnstile 的已批准 HTTPS 页面"],
website_key: Annotated[str, "页面上的精确 Turnstile 站点密钥"],
action: Annotated[str, "可选的 data-action 值"] = "",
cdata: Annotated[str, "可选的 data-cdata 值"] = "",
) -> dict:
"""为已批准的页面解决 Cloudflare Turnstile 并返回令牌。"""
parsed = urlparse(website_url)
if parsed.scheme != "https" or parsed.hostname not in ALLOWED_HOSTS:
return {
"success": False,
"error": "目标不在已批准的主机名允许列表中",
}
if not website_key.startswith("0x4"):
return {
"success": False,
"error": "意外的 Turnstile 站点密钥格式",
}
task = {
"type": "AntiTurnstileTaskProxyLess",
"websiteURL": website_url,
"websiteKey": website_key,
}
metadata = {}
if action:
metadata["action"] = action
if cdata:
metadata["cdata"] = cdata
if metadata:
task["metadata"] = metadata
try:
solution = capsolver.solve(task)
token = solution.get("token")
if not token:
return {"success": False, "error": "未返回令牌"}
return {
"success": True,
"token": token,
"solution_type": solution.get("type", "turnstile"),
}
except Exception as exc:
return {"success": False, "error": str(exc)}格式检查是一个有用的早期警告，但不能替代从授权页面中提取精确参数。在开发过程中需要检查 widget 配置时，请使用 CapSolver 浏览器扩展指南。
使用 LlamaIndex 封装函数
FunctionTool.from_defaults() 将函数签名和文档字符串转换为代理工具模式。
python
from llama_index.core.tools import FunctionTool
turnstile_tool = FunctionTool.from_defaults(
fn=solve_turnstile,
name="solve_turnstile",
description=(
"仅对已批准的 HTTPS 页面解决 Cloudflare Turnstile。"
"使用由可信浏览器控制器提供的精确页面 URL、站点密钥以及可选的 action/cdata。"
),
)保持名称简短，描述操作性。不要将工具描述为通用的访问机制。模型应理解它是在已批准的工作流内部的恢复操作。
将工具添加到 LlamaIndex FunctionAgent
LlamaIndex 的 FunctionAgent 使用 LLM 的工具调用能力来选择和执行工具。
python
from llama_index.core.agent.workflow import FunctionAgent
from llama_index.llms.openai import OpenAI
llm = OpenAI(model="gpt-4o-mini", temperature=0)
agent = FunctionAgent(
tools=[turnstile_tool],
llm=llm,
system_prompt=(
"您仅操作已批准的浏览器工作流。"
"仅当可信应用程序提供精确的页面 URL 和站点密钥时，才调用 solve_turnstile。"
"永远不要发明目标、密钥、操作或 cdata。"
"仅调用一次工具。如果失败，请停止并请求操作员审查。"
),
)通过由确定性浏览器代码生成的参数启动运行：
python
import asyncio
async def main():
response = await agent.run(
"已批准的暂存工作流在 https://staging.example.com/account-check 处发现了 Turnstile，站点密钥为 0x4AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA 并且操作为 account_check。"
"调用注册的工具一次并返回结构化结果。"
)
print(response)
asyncio.run(main())在生产环境中，避免直接从不可信用户文本构造此消息。浏览器控制器应提取、验证并序列化这些值。
将令牌消耗保留在模型之外
Turnstile 令牌是短期的，并与站点工作流相关联。在可能的情况下，直接从可信工具结果传递给确定性浏览器代码。
python
async def apply_turnstile_token(page, token: str) -> None:
await page.evaluate(
"""
(token) => {
const field = document.querySelector(
'input[name="cf-turnstile-response"]'
);
if (!field) {
throw new Error('Turnstile 响应字段未找到');
}
field.value = token;
field.dispatchEvent(new Event('input', { bubbles: true }));
field.dispatchEvent(new Event('change', { bubbles: true }));
}
""",
token,
)一些应用程序使用基于回调的渲染或服务器管理的提交。请针对自己的暂存应用程序进行测试并遵循其支持的集成方式。Cloudflare 的 Siteverify 文档 解释了站点所有者如何在服务器端验证令牌。
CapSolver Turnstile 指南 提供了实现背景，CapSolver 故障排除 FAQ 帮助诊断被拒绝的解决方案。
添加一次有限重试
不要让代理无限循环。将验证失败分类为最终状态，并允许最多一次重试以处理临时超时。
python
import asyncio
async def solve_with_policy(params: dict) -> dict:
last_error = "未知错误"
for attempt in range(1, 3):
result = solve_turnstile(**params)
if result.get("success"):
return {**result, "attempt": attempt}
last_error = result.get("error", last_error)
normalized = last_error.lower()
if "allowlist" in normalized or "site-key" in normalized:
break
if attempt == 1:
await asyncio.sleep(2)
return {
"success": False,
"error": last_error,
"requires_operator_review": True,
}记录主机名、任务类型、持续时间、尝试次数和标准化结果。永远不要记录完整的令牌、API 密钥、cookies 或表单内容。
令牌模式与浏览器模式
| 模式 | 最佳用途 | 输入 | 输出 |
|---|---|---|---|
| 令牌模式 | 已知的 Turnstile URL 和站点密钥 | URL、密钥、可选元数据 | 解决方案令牌 |
| 浏览器模式 | 现有 Playwright 会话中的动态 widget | 实时页面对象 | 页面恢复结果 |
| 人工审核 | 重复失败或不支持的状态 | 脱敏错误和截图引用 | 操作员决策 |
用户提供的 CapSolver 代理文档将 solve_captcha 映射到核心令牌求解，将 solve_on_page 映射到浏览器恢复。如果页面是动态的，请安装浏览器额外组件并保持原始浏览器会话完整：
bash
pip install "capsolver-agent[browser] @ git+https://github.com/capsolver-ai/capsolver-agent.git"使用 CapSolver 自动化教程 获取相关浏览器工作流，CapSolver 产品页面 获取支持的解决方案类别。
附加代码：在 CapSolver 仪表板 上使用代码 WEBS 可以在每次充值时获得额外的 5% 奖励。
生产控制
生产环境的 LlamaIndex Turnstile 集成应使用经过批准的主机注册表、秘密隔离、短期令牌交接、一次有限重试、日志脱敏、操作员审核以及只读自动化和高影响操作之间的严格分离。
| 控制 | 推荐实现 |
|---|---|
| 目标权限 | 租户特定的 HTTPS 允许列表 |
| 参数源 | 可信浏览器控制器 |
| 秘密存储 | 仅限执行器环境 |
| 重试策略 | 一次重试处理临时错误 |
| 令牌处理 | 直接交接给浏览器；不长期存储 |
| 跟踪 | 脱敏令牌和 cookies |
| 最终操作 | 需要确认提交或更改 |
CapSolver CAPTCHA 求解 FAQ 解释了任务生命周期，CapSolver 网络爬虫 FAQ 涵盖了操作注意事项。
负责任的使用
仅在您拥有、测试或明确授权自动化的应用程序上使用此集成。挑战求解不授予访问私有数据、创建账户、提交交易或忽略站点条款的授权。应用速率限制，维护审计跟踪，并在执行任何更改数据或影响用户的操作前要求确认。
结论
要可靠地在 LlamaIndex 中解决 Cloudflare Turnstile，将 CapSolver 作为窄范围的 FunctionTool，并将授权、秘密、重试和令牌消耗保留在确定性代码中。LlamaIndex 代理决定何时需要恢复，工具创建经过文档说明的 AntiTurnstileTaskProxyLess，浏览器使用返回的令牌继续相同的已批准工作流。
从 CapSolver 开始，针对您控制的暂存页面验证集成，并在生产前添加允许列表和日志脱敏。
FAQ
我应该使用哪个 LlamaIndex 工具类？
使用 FunctionTool.from_defaults() 来封装类型化的同步或异步 Python 函数。对于工具调用模型，将生成的工具传递给 FunctionAgent。
Turnstile 任务是否需要代理？
经过文档说明的 AntiTurnstileTaskProxyLess 使用 CapSolver 的无代理任务路径，因此您不需要在任务中提供代理。
哪些字段是必需的？
websiteURL 和 websiteKey 是必需的。仅在授权 widget 暴露它们时包含 metadata.action 和 metadata.cdata。
应该将令牌存储在 LlamaIndex 内存中吗？
不。优先将令牌直接交接给可信浏览器代码，并仅将脱敏的成功或失败状态返回给代理。
重复失败后应该发生什么？
验证 URL、站点密钥、可选元数据和页面状态。在一次有限重试后，停止并将工作流路由到操作员审核。