SDK 概览与系统架构

概述

oxylabs-ai-studio-py 是 Oxylabs AI Studio 服务的官方 Python SDK，为 AI-Scraper、AI-Crawler、AI-Browser-Agent 等数据提取工具提供统一、同步/异步双模式的 Python 调用入口。该 SDK 面向 Python 3.10 及以上环境，开发者只需提供 API Key 即可与 Oxylabs AI Studio 后端交互 资料来源：readme.md:1-20。

按照 README 中的描述，SDK 通过一组面向"应用（app）"的高层封装，将 HTTP 请求、任务轮询、结果解析等细节屏蔽，使用户能够通过自然语言提示（user_prompt）和 JSON Schema 定义目标数据格式 资料来源：readme.md:21-90。

系统架构

整个 SDK 采用"客户端（Client）— 应用（App）— 后端 API"三层结构。客户端负责管理 HTTP 连接、API Key 和基础 URL；应用层封装具体的业务能力（Scraper / Crawler / Browser Agent / Search / Map）；后端由 Oxylabs AI Studio 统一托管。每个应用既支持同步方法也提供 *_async 异步变体。

flowchart LR
    User[Python 调用方] --> Apps
    subgraph Apps[SDK 应用层]
        AS[AiScraper]
        AC[AiCrawler]
        BA[BrowserAgent]
        AX[AiSearch]
        AM[AiMap]
    end
    Apps --> Client[Client 同步/异步]
    Client -->|HTTPS| API[(Oxylabs AI Studio API)]
    API -->|轮询 run_id| Client
    Client --> Apps
    Apps --> User

应用层通过 call_api / call_api_async 与后端通信，提交任务后会拿到 run_id 并进入 POLL_MAX_ATTEMPTS 轮询循环，根据返回状态（processing / completed）决定继续等待还是返回结果对象 资料来源：src/oxylabs_ai_studio/apps/ai_crawler.py:38-90。

核心组件

SDK 将能力拆分为多个互不耦合的应用对象，每个对象对应一个数据采集场景。

AiScraper —— 单页结构化抓取

AiScraper 用于抓取单个 URL 的页面内容并以 Markdown / HTML / JSON / CSV / Screenshot / Toon 等格式返回。当 output_format 为 json、csv 或 toon 时，调用方必须提供 openapi_schema，否则会抛出 ValueError 资料来源：src/oxylabs_ai_studio/apps/ai_scraper.py:30-60。

generate_schema / generate_schema_async 可根据自然语言提示自动生成 OpenAPI Schema，从而免去手写 JSON Schema 的负担 资料来源：src/oxylabs_ai_studio/apps/ai_scraper.py:1-25。

AiCrawler —— 站点级抓取

AiCrawler 在 AiScraper 的基础上引入多页爬取与多源汇总能力。请求体除了 url 与 user_prompt，还包含 render_javascript、return_sources_limit、geo_location 与 max_credits 等字段；其结果以 AiCrawlerJob.data 列表形式逐条返回 资料来源：src/oxylabs_ai_studio/apps/ai_crawler.py:20-90。典型用法是先 generate_schema 推断出价格/特性字段，再遍历 result.data 资料来源：examples/crawl_generated_schema.py:1-19。

BrowserAgent —— 浏览器代理

BrowserAgent 是面向交互式站点的代理型接口，支持 json / markdown / html / screenshot / csv / toon 等输出格式，并由 geo_location 控制代理地理位置 资料来源：src/oxylabs_ai_studio/apps/browser_agent.py:20-60。示例中演示了从沙箱商店搜索 "super mario odyssey" 并提取价格的过程 资料来源：examples/browser_agent.py:1-20。

AiSearch / AiMap

AiSearch 提供同步与即时（instant_search）两种入口，当 limit <= 10 且 return_content=False 时会自动走 /search/instant 端点以减少延迟 资料来源：readme.md:42-68。AiMap 用于按关键词与爬取深度（max_crawl_depth）枚举站点 URL 资源，并可选择是否纳入 sitemap 与子域 资料来源：examples/ai_map.py:1-18。

同步/异步双接口模式

所有应用都同时提供 method 和 method_async 两套接口，二者共享同一份业务参数，但底层 HTTP 客户端分别为同步 httpx.Client 与异步 httpx.AsyncClient 资料来源：src/oxylabs_ai_studio/apps/ai_scraper.py:60-120。这种设计让 SDK 既能直接被脚本使用，也能在 asyncio 事件循环中与其他异步任务并行。

请求生命周期与公共类型

典型的请求生命周期为：构造请求体 → POST 启动端点 → 取得 run_id → 轮询数据端点 → 返回 *Job 对象。后端对每个应用都暴露了 generate-params（或 schema）端点，用于把自然语言转换为 OpenAPI Schema，其响应均通过 SchemaResponse 类型承载 资料来源：src/oxylabs_ai_studio/models.py:1-8。

常见失败模式：当结构化输出未提供 schema 时，SDK 会直接抛出 ValueError；当 HTTP 状态码非 200 时，会抛出包含响应正文的 Exception；当轮询超时时，AiScraper 会抛出 Error("Failed to scrape {url}: timeout.") 资料来源：src/oxylabs_ai_studio/apps/ai_scraper.py:1-5。

社区与版本说明

最新发布版本 v0.2.19 的主要变化是从 map 应用中移除了已弃用的端点 资料来源：v0.2.19 Release Notes。仓库当前公开的社区反馈较少，开发者使用过程中如遇问题可在仓库 issue 区反馈，Oxylabs 也通过 Discord 与 YouTube 渠道提供支持 资料来源：readme.md:3-7。

See Also

• AI Scraper 使用详解
• AI Crawler 与多页抓取
• Browser Agent 浏览器代理指南
• AI Search / AI Map 搜索与站点映射

数据提取应用：Scraper、Crawler 和 Browser Agent

概述

oxylabs-ai-studio-py 库在 oxylabs_ai_studio.apps 包下提供了三种面向"网页数据提取"场景的应用客户端：AiScraper、AiCrawler 与 BrowserAgent（数据模型在 src/oxylabs_ai_studio/models.py 中以 SchemaResponse 形式约定） 资料来源：src/oxylabs_ai_studio/models.py。三者的共同点在于：均通过自然语言 prompt 与可选的 JSON Schema 来引导抽取过程，并提供同步与异步两套接口。区别在于适用的网页范围与交互深度：AiScraper 处理单页，AiCrawler 在多页间爬取，BrowserAgent 模拟真实浏览器在页面内部进行交互。资料来源：readme.md, agentic_code_guide.md。

在 v0.2.19 版本中，开发团队移除了 map 应用中的已弃用端点，说明项目处于持续重构阶段，依赖最新的接口约定时需关注发布说明。资料来源：GitHub Releases v0.2.19。

AiScraper（AI 抓取器）

AiScraper 面向"单页内容抓取"场景，将目标 URL 的内容以 Markdown、JSON、CSV、TOON 或 Screenshot 形式返回 资料来源：src/oxylabs_ai_studio/apps/ai_scraper.py。其关键参数包括：

• url：待抓取的目标 URL（必填）。
• output_format：取值 "json" | "markdown" | "csv" | "screenshot" | "toon"，默认 "markdown"。
• openapi_schema：当 output_format 为 "json" | "csv" | "toon" 时必填，校验逻辑会主动抛出 ValueError。
• render_javascript：布尔值或 "auto"，控制是否启用 JS 渲染。
• geo_location 与 user_agent：用于代理与请求头控制。

下面的示例展示最简的 Markdown 抓取 资料来源：examples/scrape_markdown.py：

from oxylabs_ai_studio.apps.ai_scraper import AiScraper

scraper = AiScraper(api_key="<API_KEY>")
result = scraper.scrape(
    url="https://sandbox.oxylabs.io/products/1",
    output_format="markdown",
    render_javascript=False,
    geo_location="Germany",
)
print(result)

若希望得到结构化 JSON，可以直接传入 Pydantic 模型的 model_json_schema()，或使用 generate_schema 让服务端根据自然语言 prompt 反向生成 Schema 资料来源：examples/scrape_pydantic_schema.py, examples/scrape_generated_schema.py。异步版本 scrape_async 与 generate_schema_async 通过 httpx.AsyncClient 发起请求，调用方式与同步接口完全一致 资料来源：src/oxylabs_ai_studio/apps/ai_scraper.py。

AiCrawler（AI 爬虫）

AiCrawler 适用于"从一个起始 URL 出发，沿站内链接发现多页内容"的场景，其结果通常是 list[Item] 资料来源：src/oxylabs_ai_studio/apps/ai_crawler.py。与 AiScraper 相比，它额外引入了 user_prompt 用于表达"应该抓哪些页面"以及 return_sources_limit 控制返回页面数；output_format 不再支持 "screenshot"，但保留了 json/markdown/csv/toon 资料来源：readme.md。max_credits 参数则用于为单次任务设定额度上限。

from oxylabs_ai_studio.apps.ai_crawler import AiCrawler

crawler = AiCrawler(api_key="<API_KEY>")
result = crawler.crawl(
    url="https://oxylabs.io",
    user_prompt="Find all pages with proxy products pricing",
    output_format="markdown",
    render_javascript=False,
    return_sources_limit=3,
    geo_location="France",
)
for item in result.data:
    print(item, "\n")

Schema 的三种使用方式——内联字典、Pydantic 模型、API 生成——在 examples/crawl_pydantic_schema.py、examples/crawl_generated_schema.py 中均有覆盖。异步版本 crawl_async 与 generate_schema 同样存在，行为对齐 资料来源：src/oxylabs_ai_studio/apps/ai_crawler.py。

BrowserAgent（浏览器代理）

BrowserAgent 适合需要"点击、翻页、填表、登录"等真实交互的场景。它在云端启动一个浏览器实例，根据 user_prompt 自动完成导航与提取，并支持 output_format 为 "html" 或 "screenshot"，这两种格式是 AiScraper/AiCrawler 都不具备的 资料来源：src/oxylabs_ai_studio/apps/browser_agent.py, agentic_code_guide.md。典型用法如下 资料来源：examples/browser_agent.py：

from oxylabs_ai_studio.apps.browser_agent import BrowserAgent

browser_agent = BrowserAgent(api_key="<API_KEY>")
schema = browser_agent.generate_schema(
    prompt="game name, platform, review stars and price"
)
result = browser_agent.run(
    url="https://sandbox.oxylabs.io/",
    user_prompt="Find if there is game 'super mario odyssey' in the store...",
    output_format="json",
    schema=schema,
    geo_location="Spain",
)
print(result.data)

agentic_code_guide.md 给出了一个组合用法：先用 BrowserAgent 找到分类页与翻页 URL，再用 AiScraper 批量抽取商品字段 资料来源：agentic_code_guide.md。

三者对比与选型

下表总结了三种应用在"输入、输出、典型场景"上的关键差异，便于按需选择 资料来源：src/oxylabs_ai_studio/apps/ai_scraper.py, src/oxylabs_ai_studio/apps/ai_crawler.py, src/oxylabs_ai_studio/apps/browser_agent.py, readme.md。

常见失败模式

• 未传 Schema：当 output_format ∈ {json, csv, toon} 而未提供 openapi_schema 时，三个应用都会抛 ValueError 资料来源：src/oxylabs_ai_studio/apps/ai_scraper.py。
• 长任务超时：客户端使用 POLL_MAX_ATTEMPTS 轮询结果，长时间任务在达到上限时会抛 Error("...timeout.") 异常 资料来源：src/oxylabs_ai_studio/apps/ai_scraper.py。
• 端点变更：map 应用在 v0.2.19 中移除了已弃用端点，升级后需参考发布说明同步调用方式 资料来源：GitHub Releases v0.2.19。

See Also

• 数据搜索类应用 AiSearch、AiMap 的使用说明见 readme.md。
• 端到端电商抽取工作流示例见 agentic_code_guide.md。

Discovery Apps: AI Search 和 AI Map

概述与定位

oxylabs-ai-studio-py 是 Oxylabs AI Studio API 的官方 Python SDK,提供了多个面向"数据发现"场景的应用模块。其中 AiSearch 与 AiMap 同属于"发现类 (Discovery)"应用,二者均不直接抓取并解析页面正文,而是用于在大范围网页或搜索引擎结果中发现、筛选与定位目标 URL,通常作为 AiCrawler 与 AiScraper 等下游采集工具的前置步骤使用 (readme.md)。

• AiSearch:封装搜索引擎 (SERP) 结果查询接口,支持普通搜索 (search) 与即时搜索 (instant_search) 两种模式。
• AiMap:基于起始 URL 探索站点结构,返回与关键词/提示词匹配的 URL 列表,常用于站点地图构建与目标页面发现 (examples/ai_map.py)。

两个应用都遵循统一的客户端构造方式,通过 api_key="<API_KEY>" 注入认证凭据即可发起调用 (examples/search_with_content.py)。

配置与初始化

所有应用类（AiScraper、AiCrawler、BrowserAgent、AiMap、AiSearch）在构造时通过 api_key 关键字参数接收凭据，没有外部配置文件或环境变量读取逻辑（用户需自行管理密钥）。

from oxylabs_ai_studio.apps.ai_scraper import AiScraper
scraper = AiScraper(api_key="<API_KEY>")

资料来源：examples/scrape_markdown.py:3

SDK 的最小运行要求为 Python 3.10 及以上，并且必须提供 API 密钥（readme.md "Requirements"）。

客户端内部机制

同步 / 异步双接口

每个应用类同时暴露 scrape / scrape_async、crawl / crawl_async、run / run_async 等方法。同步实现使用普通 HTTP 客户端轮询，异步实现使用 httpx.AsyncClient，但两者的接口参数与返回结构保持一致（src/oxylabs_ai_studio/apps/ai_scraper.py、src/oxylabs_ai_studio/apps/browser_agent.py）。

轮询状态机

SDK 通过 提交 → 轮询 的两阶段模式获取结果。以 BrowserAgent.run_async 为例：

sequenceDiagram
    participant App as BrowserAgent
    participant API as AI Studio API
    App->>API: POST /browser-agent/run
    API-->>App: 200 {run_id}
    loop 最多 POLL_MAX_ATTEMPTS 次
        App->>API: GET /browser-agent/run/data?run_id=...
        API-->>App: 202 继续等待
        API-->>App: 200 status=processing
        API-->>App: 200 status=completed / failed
    end

• POLL_MAX_ATTEMPTS 与 POLL_INTERVAL_SECONDS 控制轮询上限与间隔（src/oxylabs_ai_studio/apps/browser_agent.py）。
• HTTP 202 表示仍在排队 / 处理中，客户端会 sleep 后继续（src/oxylabs_ai_studio/apps/browser_agent.py）。
• 返回体的 status 字段决定终态：completed 携带 data，failed 则 data 为 None 并通过 message 暴露 error_code（src/oxylabs_ai_studio/apps/browser_agent.py）。

Schema 与输出格式约束

所有结构化输出（json / csv / toon）要求调用方提供 OpenAPI/JSON Schema，否则在客户端直接抛出 ValueError。模型返回结构在 models.py 中定义为 SchemaResponse(TypedDict)，字段为 openapi_schema（src/oxylabs_ai_studio/models.py）。

支持的输出格式：json、markdown、html、screenshot、csv、toon（src/oxylabs_ai_studio/apps/ai_scraper.py、src/oxylabs_ai_studio/apps/browser_agent.py）。

通用使用模式

模式一：自动生成 Schema

利用 generate_schema(prompt=...) 将自然语言转为 JSON Schema，适合对目标字段不确定的场景：

schema = scraper.generate_schema(prompt="want to parse developer, platform, type, price game title, genre (array) and description")
result = scraper.scrape(url=url, output_format="json", schema=schema, render_javascript=False)

资料来源：examples/scrape_generated_schema.py:5-9

AiCrawler 与 BrowserAgent 也提供同名方法，分别命中 /crawl/generate-params 与 /browser-agent/generate-params（src/oxylabs_ai_studio/apps/ai_crawler.py、src/oxylabs_ai_studio/apps/browser_agent.py）。

模式二：使用 Pydantic 显式声明 Schema

对于稳定的业务结构，推荐用 Pydantic 模型并通过 model.model_json_schema() 转换，兼顾类型校验与文档可读性：

class ProxyPlan(BaseModel):
    name: str = Field(description="The name of the proxy plan")
    price: str = Field(description="The price of the proxy plan")
    features: list[str] = Field(description="The features of the proxy plan")

资料来源：examples/crawl_pydantic_schema.py:6-13

模式三：定位 + 提取组合

agentic_code_guide.md 给出电商抓取典型工作流：先用 BrowserAgent 发现分页 URL，再用 AiScraper 抓取列表与详情（agentic_code_guide.md "E-commerce Product Scraping"）。

模式四：地理代理与即时搜索

通过 geo_location 指定 ISO2 / 国家规范名切换出口 IP（examples/scrape_markdown.py、examples/crawl_markdown.py）。当 limit <= 10 且 return_content=False 时，AiSearch 会自动路由到 /search/instant 即时端点，跳过轮询（readme.md "Search" 节）。

错误处理与常见失败模式

社区方面，最新发布 v0.2.19 移除了 map 应用中的已废弃端点（v0.2.19 release notes），升级时需检查是否仍在调用旧路径。

See Also

• AI Scraper / Crawler / Browser Agent 应用参考
• BrowserAgent 轮询与状态机源码
• AI-Scraper 应用源码
• Agentic 工作流指南

Pitfall Log / 踩坑日志

项目：oxylabs/oxylabs-ai-studio-py

摘要：发现 7 个潜在踩坑项，其中 0 个为 high/blocking；最高优先级：身份坑 - 仓库名和安装名不一致。

1. 身份坑 · 仓库名和安装名不一致

• 严重度：medium
• 证据强度：runtime_trace
• 发现：仓库名 oxylabs-ai-studio-py 与安装入口 oxylabs-ai-studio 不完全一致。
• 对用户的影响：用户照着仓库名搜索包或照着包名找仓库时容易走错入口。
• 复现命令：pip install oxylabs-ai-studio
• 证据：identity.distribution | https://github.com/oxylabs/oxylabs-ai-studio-py | repo=oxylabs-ai-studio-py; install=oxylabs-ai-studio

2. 能力坑 · 能力判断依赖假设

• 严重度：medium
• 证据强度：source_linked
• 发现：README/documentation is current enough for a first validation pass.
• 对用户的影响：假设不成立时，用户拿不到承诺的能力。
• 证据：capability.assumptions | https://github.com/oxylabs/oxylabs-ai-studio-py | README/documentation is current enough for a first validation pass.

3. 维护坑 · 维护活跃度未知

• 严重度：medium
• 证据强度：source_linked
• 发现：未记录 last_activity_observed。
• 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。
• 证据：evidence.maintainer_signals | https://github.com/oxylabs/oxylabs-ai-studio-py | last_activity_observed missing

• 严重度：medium
• 证据强度：source_linked
• 发现：no_demo
• 证据：downstream_validation.risk_items | https://github.com/oxylabs/oxylabs-ai-studio-py | no_demo; severity=medium

5. 安全/权限坑 · 存在评分风险

• 严重度：medium
• 证据强度：source_linked
• 发现：no_demo
• 对用户的影响：风险会影响是否适合普通用户安装。
• 证据：risks.scoring_risks | https://github.com/oxylabs/oxylabs-ai-studio-py | no_demo; severity=medium

6. 维护坑 · issue/PR 响应质量未知

• 严重度：low
• 证据强度：source_linked
• 发现：issue_or_pr_quality=unknown。
• 对用户的影响：用户无法判断遇到问题后是否有人维护。
• 证据：evidence.maintainer_signals | https://github.com/oxylabs/oxylabs-ai-studio-py | issue_or_pr_quality=unknown

7. 维护坑 · 发布节奏不明确

• 严重度：low
• 证据强度：source_linked
• 发现：release_recency=unknown。
• 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。
• 证据：evidence.maintainer_signals | https://github.com/oxylabs/oxylabs-ai-studio-py | release_recency=unknown