CAPSOLVER
博客
如何在 LlamaIndex 代理中解决验证码

如何在LlamaIndex智能代理中解决验证码

Logo of CapSolver

Ethan Collins

Pattern Recognition Specialist

31-Jul-2026

LlamaIndex 代理协调跨多种来源的数据检索、索引和查询工作流。当这些代理访问受 CAPTCHA 挑战保护的基于网络的数据源时,需要一种解决机制以继续数据摄取。CapSolver 的 capsolver-agent 包提供了与 LlamaIndex 的 FunctionTool 系统兼容的工具模式,使您的代理能够作为数据管道的一部分清除 reCAPTCHA、Cloudflare Turnstile 和其他验证挑战。

TL;DR

  • 当网络数据源受到 CAPTCHA 验证保护时,LlamaIndex 代理会停滞
  • CapSolver 通过 LlamaIndex 的 FunctionTool 包装器异步集成
  • capsolver-agent 执行器处理解决并返回结构化结果,供代理的推理循环使用
  • 支持 reCAPTCHA v2/v3 和 Cloudflare Turnstile —— 最常见的网页验证类型
  • 使用 create_executor()FunctionTool.from_defaults() 在 15 行以内完成集成

为什么 LlamaIndex 代理需要 CAPTCHA 解决方案

LlamaIndex 在构建从多个来源检索、索引和查询数据的代理方面表现出色。当这些来源包括受 CAPTCHA 系统保护的网页、API 或数据库时,代理的数据摄取管道会中断。需要从受 CAPTCHA 保护的网站索引文档的 RAG 代理,或查询多个网络来源的研究代理,若未清除验证将无法继续。

对于 LlamaIndex 的数据连接器生态系统来说,这个问题尤为严重。那些用于索引抓取页面的基于网络的连接器在多次访问后会遇到 CAPTCHA。没有解决工具,代理要么跳过该来源(数据不完整),要么完全失败(管道中断)。

CapSolver 的工具集成遵循 LlamaIndex 的标准模式:定义一个函数,将其包装为 FunctionTool,并添加到代理的工具列表中。代理的推理引擎根据任务上下文决定何时调用解决功能。

开始前需要准备的内容

bash 复制代码
# CapSolver 包
pip install git+https://github.com/capsolver-ai/capsolver-core.git
pip install git+https://github.com/capsolver-ai/capsolver-agent.git

# LlamaIndex
pip install llama-index llama-index-llms-openai
bash 复制代码
export CAPSOLVER_API_KEY="your-capsolver-api-key"
export OPENAI_API_KEY="your-openai-api-key"

第 1 步 —— 创建 CAPTCHA 解决 FunctionTool

python 复制代码
import asyncio
from llama_index.core.tools import FunctionTool
from capsolver_agent.schema import create_executor

executor = create_executor(api_key="YOUR_CAPSOLVER_API_KEY")

def solve_captcha(captcha_type: str, website_url: str, website_key: str) -> str:
    """解决 CAPTCHA 挑战并返回验证令牌。
    
    在访问受 CAPTCHA 验证保护的网络资源时使用。
    
    参数:
        captcha_type: 'reCaptchaV2', 'reCaptchaV3' 或 'cloudflare'
        website_url: 受 CAPTCHA 保护的页面完整 URL
        website_key: 网站密钥(data-sitekey 属性值)
    
    返回:
        解决的令牌字符串或错误信息
    """
    result = asyncio.run(executor.execute("solve_captcha", {
        "captcha_type": captcha_type,
        "website_url": website_url,
        "website_key": website_key
    }))
    if result["success"]:
        return f"CAPTCHA 已解决。令牌: {result['solution']['token']}"
    return f"失败: {result['error']}"

# 包装为 LlamaIndex FunctionTool
captcha_tool = FunctionTool.from_defaults(
    fn=solve_captcha,
    name="solve_captcha",
    description="在受保护的网页上解决 reCAPTCHA v2/v3 和 Cloudflare Turnstile CAPTCHA 挑战"
)

第 2 步 —— 构建具有 CAPTCHA 功能的 LlamaIndex 代理

python 复制代码
from llama_index.core.agent import ReActAgent
from llama_index.llms.openai import OpenAI

# 创建 LLM
llm = OpenAI(model="gpt-4o", temperature=0)

# 创建具有 CAPTCHA 解决工具的代理
agent = ReActAgent.from_tools(
    tools=[captcha_tool],
    llm=llm,
    verbose=True
)

# 运行代理
response = agent.chat(
    "我需要访问 https://example.com/data,它有 reCAPTCHA v2。"
    "网站密钥是 6LeIxAcTAAAAAJcZVRqyHh71UMIEGNQ_MXjiZKhI。"
    "解决它并给我令牌。"
)
print(response)

第 3 步 —— 与 LlamaIndex 数据连接器集成

对于摄取网络数据的代理,将 CAPTCHA 解决与数据加载结合:

python 复制代码
from llama_index.core import VectorStoreIndex, Document

def fetch_protected_page(url: str, site_key: str) -> str:
    """通过先解决 CAPTCHA 来获取受保护的页面。"""
    # 解决 CAPTCHA
    token = solve_captcha("reCaptchaV2", url, site_key)
    if "失败" in token:
        return ""
    
    # 使用令牌访问页面
    import requests
    response = requests.post(url, data={"g-recaptcha-response": token.split("令牌: ")[1]})
    return response.text

# 创建用于受保护数据摄取的自定义工具
protected_fetch_tool = FunctionTool.from_defaults(
    fn=fetch_protected_page,
    name="fetch_protected_page",
    description="通过先解决验证来获取受保护的网页内容"
)

# 具有解决和获取能力的代理
data_agent = ReActAgent.from_tools(
    tools=[captcha_tool, protected_fetch_tool],
    llm=llm,
    verbose=True
)

第 4 步 —— 生产模式

python 复制代码
def solve_captcha_with_retry(captcha_type: str, website_url: str, website_key: str, max_retries: int = 3) -> str:
    """具有重试逻辑的生产级 CAPTCHA 解决方案。"""
    for attempt in range(max_retries):
        result = asyncio.run(executor.execute("solve_captcha", {
            "captcha_type": captcha_type,
            "website_url": website_url,
            "website_key": website_key
        }))
        if result["success"]:
            return f"已解决(尝试 {attempt+1})。令牌: {result['solution']['token']}"
        if attempt < max_retries - 1:
            import time
            time.sleep(3)
    return f"尝试 {max_retries} 次后失败: {result.get('error')}"

# 具有重试功能的生产工具
production_captcha_tool = FunctionTool.from_defaults(
    fn=solve_captcha_with_retry,
    name="solve_captcha",
    description="在失败时自动重试的 CAPTCHA 解决方案"
)
CAPTCHA 类型 参数 解决时间 每 1K 成本
reCAPTCHA v2 reCaptchaV2 5-12 秒 $2-3
reCAPTCHA v3 reCaptchaV3 3-8 秒 $1-2
Cloudflare Turnstile cloudflare 2-5 秒 $1-2

领取您的优惠码:在 CapSolver 仪表板 使用代码 WEBS,每次充值可额外获得 5% 奖励。

CapSolver API 文档 涵盖了其他参数。要识别 CAPTCHA 类型,请使用 CapSolver 扩展CapSolver 网络抓取指南 涵盖了适用于 LlamaIndex 数据连接器的数据收集模式。

结论

将 CAPTCHA 解决方案集成到 LlamaIndex 代理中需要将 CapSolver 的执行器包装成 FunctionTool,并将其添加到 ReAct 代理的工具列表中。代理的推理循环根据任务上下文决定何时调用解决功能。CapSolver 提供了通过统一 API 处理 reCAPTCHA 和 Cloudflare Turnstile 的解决基础设施,确保您的 LlamaIndex 数据管道不间断运行。

FAQ

CapSolver 是否与 LlamaIndex 的异步代理兼容?

是的。capsolver-agent 执行器是完全异步的。对于 LlamaIndex 的异步代理,请直接使用 await executor.execute() 而不是 asyncio.run() 包装。

我可以将此与 LlamaIndex 的网络阅读器连接器一起使用吗?

是的。将 CAPTCHA 解决工具与处理验证后获取页面内容的自定义网络阅读器结合使用。代理可以先解决 CAPTCHA,然后将令牌传递给网络阅读器以进行身份验证访问。

如果我的 LlamaIndex 代理遇到未知的 CAPTCHA 类型怎么办?

get_supported_captchas 工具会返回支持的类型列表。如果代理遇到不支持的类型,会收到明确的错误信息,并可以向用户报告而不是静默失败。

这与使用 capsolver-mcp 与 LlamaIndex 相比如何?

capsolver-mcp 用于 MCP 客户端(Claude Desktop、Cursor)。对于在代码中运行的 LlamaIndex 代理,请使用 capsolver-agentFunctionTool —— 它在 LlamaIndex 框架内提供了直接的程序控制。

合规声明: 本博客提供的信息仅供参考。CapSolver 致力于遵守所有适用的法律和法规。严禁以非法、欺诈或滥用活动使用 CapSolver 网络,任何此类行为将受到调查。我们的验证码解决方案在确保 100% 合规的同时,帮助解决公共数据爬取过程中的验证码难题。我们鼓励负责任地使用我们的服务。如需更多信息,请访问我们的服务条款和隐私政策。

更多