{
"canonical_name": "oxylabs/oxylabs-ai-studio-py",
"compilation_id": "pack_942b73dbfb774c60b469709ad7caa99d",
"created_at": "2026-05-14T01:21:58.395892+00:00",
"created_by": "project-pack-compiler",
"feedback": {
"carrier_selection_notes": [
"viable_asset_types=prompt, recipe, host_instruction, eval, preflight",
"recommended_asset_types=prompt, recipe, host_instruction, eval, preflight"
],
"evidence_delta": {
"confirmed_claims": [
"identity_anchor_present",
"capability_and_host_targets_present",
"install_path_declared_or_better"
],
"missing_required_fields": [],
"must_verify_forwarded": [
"Run or inspect `pip install oxylabs-ai-studio` in an isolated environment.",
"Confirm the project exposes the claimed capability to at least one target host."
],
"quickstart_execution_scope": "allowlisted_sandbox_smoke",
"sandbox_command": "pip install oxylabs-ai-studio",
"sandbox_container_image": "python:3.12-slim",
"sandbox_execution_backend": "docker",
"sandbox_planner_decision": "llm_execute_isolated_install",
"sandbox_validation_id": "sbx_21956381ba104e288864ad19883fa56a"
},
"feedback_event_type": "project_pack_compilation_feedback",
"learning_candidate_reasons": [],
"template_gaps": []
},
"identity": {
"canonical_id": "project_2b69f1c1199039ddb0cc114e699c36ef",
"canonical_name": "oxylabs/oxylabs-ai-studio-py",
"homepage_url": null,
"license": "unknown",
"repo_url": "https://github.com/oxylabs/oxylabs-ai-studio-py",
"slug": "oxylabs-ai-studio-py",
"source_packet_id": "phit_cdb549ccb0e24dfdaf14da83f707fe2e",
"source_validation_id": "dval_79126fc4f2384013954c78fe80c83a06"
},
"merchandising": {
"best_for": "需要软件开发与交付能力，并使用 local_cli的用户",
"github_forks": 25,
"github_stars": 2898,
"one_liner_en": "Structured data gathering from any website using AI-powered scraper, crawler, and browser automation. Scraping and crawling with natural language prompts. Equip your LLM agents with fresh data. AI Studio python SDK for intelligent web data gathering.",
"one_liner_zh": "Structured data gathering from any website using AI-powered scraper, crawler, and browser automation. Scraping and crawling with natural language prompts. Equip your LLM agents with fresh data. AI Studio python SDK for intelligent web data gathering.",
"primary_category": {
"category_id": "software-development",
"confidence": "high",
"name_en": "Software Development",
"name_zh": "软件开发与交付",
"reason": "matched_keywords:git, cli, sdk"
},
"target_user": "使用 local_cli 等宿主 AI 的用户",
"title_en": "oxylabs-ai-studio-py",
"title_zh": "oxylabs-ai-studio-py 能力包",
"visible_tags": [
{
"label_en": "Browser Agents",
"label_zh": "浏览器 Agent",
"source": "repo_evidence_project_characteristics",
"tag_id": "product_domain-browser-agents",
"type": "product_domain"
},
{
"label_en": "Web Task Automation",
"label_zh": "网页任务自动化",
"source": "repo_evidence_project_characteristics",
"tag_id": "user_job-web-task-automation",
"type": "user_job"
},
{
"label_en": "Natural-language Web Actions",
"label_zh": "自然语言网页操作",
"source": "repo_evidence_project_characteristics",
"tag_id": "core_capability-natural-language-web-actions",
"type": "core_capability"
},
{
"label_en": "Automated Workflow",
"label_zh": "自动化工作流",
"source": "repo_evidence_project_characteristics",
"tag_id": "workflow_pattern-automated-workflow",
"type": "workflow_pattern"
},
{
"label_en": "Structured Data Extraction",
"label_zh": "结构化数据提取",
"source": "repo_evidence_project_characteristics",
"tag_id": "selection_signal-structured-data-extraction",
"type": "selection_signal"
}
]
},
"packet_id": "phit_cdb549ccb0e24dfdaf14da83f707fe2e",
"page_model": {
"artifacts": {
"artifact_slug": "oxylabs-ai-studio-py",
"files": [
"PROJECT_PACK.json",
"QUICK_START.md",
"PROMPT_PREVIEW.md",
"HUMAN_MANUAL.md",
"AI_CONTEXT_PACK.md",
"BOUNDARY_RISK_CARD.md",
"PITFALL_LOG.md",
"REPO_INSPECTION.json",
"REPO_INSPECTION.md",
"CAPABILITY_CONTRACT.json",
"EVIDENCE_INDEX.json",
"CLAIM_GRAPH.json"
],
"required_files": [
"PROJECT_PACK.json",
"QUICK_START.md",
"PROMPT_PREVIEW.md",
"HUMAN_MANUAL.md",
"AI_CONTEXT_PACK.md",
"BOUNDARY_RISK_CARD.md",
"PITFALL_LOG.md",
"REPO_INSPECTION.json"
]
},
"detail": {
"capability_source": "Project Hit Packet + DownstreamValidationResult",
"commands": [
{
"command": "pip install oxylabs-ai-studio",
"label": "Python / pip · 官方安装入口",
"source": "https://github.com/oxylabs/oxylabs-ai-studio-py#readme",
"verified": true
}
],
"display_tags": [
"浏览器 Agent",
"网页任务自动化",
"自然语言网页操作",
"自动化工作流",
"结构化数据提取"
],
"eyebrow": "软件开发与交付",
"glance": [
{
"body": "判断自己是不是目标用户。",
"label": "最适合谁",
"value": "需要软件开发与交付能力，并使用 local_cli的用户"
},
{
"body": "先理解能力边界，再决定是否继续。",
"label": "核心价值",
"value": "Structured data gathering from any website using AI-powered scraper, crawler, and browser automation. Scraping and crawling with natural language prompts. Equip your LLM agents with fresh data. AI Studio python SDK for intelligent web data gathering."
},
{
"body": "未完成验证前保持审慎。",
"label": "继续前",
"value": "publish to Doramagic.ai project surfaces"
}
],
"guardrail_source": "Boundary & Risk Card",
"guardrails": [
{
"body": "Prompt Preview 只展示流程，不证明项目已安装或运行。",
"label": "Check 1",
"value": "不要把试用当真实运行"
},
{
"body": "local_cli",
"label": "Check 2",
"value": "确认宿主兼容"
},
{
"body": "publish to Doramagic.ai project surfaces",
"label": "Check 3",
"value": "先隔离验证"
}
],
"mode": "prompt, recipe, host_instruction, eval, preflight",
"pitfall_log": {
"items": [
{
"body": "仓库名 `oxylabs-ai-studio-py` 与安装入口 `oxylabs-ai-studio` 不完全一致。",
"category": "身份坑",
"evidence": [
"identity.distribution | github_repo:1003630893 | https://github.com/oxylabs/oxylabs-ai-studio-py | repo=oxylabs-ai-studio-py; install=oxylabs-ai-studio"
],
"severity": "medium",
"suggested_check": "在 npm/PyPI/GitHub 上确认包名映射和官方 README 说明。",
"title": "仓库名和安装名不一致",
"user_impact": "用户照着仓库名搜索包或照着包名找仓库时容易走错入口。"
},
{
"body": "README/documentation is current enough for a first validation pass.",
"category": "能力坑",
"evidence": [
"capability.assumptions | github_repo:1003630893 | https://github.com/oxylabs/oxylabs-ai-studio-py | README/documentation is current enough for a first validation pass."
],
"severity": "medium",
"suggested_check": "将假设转成下游验证清单。",
"title": "能力判断依赖假设",
"user_impact": "假设不成立时，用户拿不到承诺的能力。"
},
{
"body": "GitHub 社区证据显示该项目存在一个维护/版本相关的待验证问题：v.0.2.19",
"category": "维护坑",
"evidence": [
"community_evidence:github | cevd_96a2e22cbea94aac8c2788f763ce7c04 | https://github.com/oxylabs/oxylabs-ai-studio-py/releases/tag/v0.2.19 | 来源类型 github_release 暴露的待验证使用条件。"
],
"severity": "medium",
"suggested_check": "来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。",
"title": "来源证据：v.0.2.19",
"user_impact": "可能影响升级、迁移或版本选择。"
},
{
"body": "未记录 last_activity_observed。",
"category": "维护坑",
"evidence": [
"evidence.maintainer_signals | github_repo:1003630893 | https://github.com/oxylabs/oxylabs-ai-studio-py | last_activity_observed missing"
],
"severity": "medium",
"suggested_check": "补 GitHub 最近 commit、release、issue/PR 响应信号。",
"title": "维护活跃度未知",
"user_impact": "新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。"
},
{
"body": "no_demo",
"category": "安全/权限坑",
"evidence": [
"downstream_validation.risk_items | github_repo:1003630893 | https://github.com/oxylabs/oxylabs-ai-studio-py | no_demo; severity=medium"
],
"severity": "medium",
"suggested_check": "进入安全/权限治理复核队列。",
"title": "下游验证发现风险项",
"user_impact": "下游已经要求复核，不能在页面中弱化。"
},
{
"body": "No sandbox install has been executed yet; downstream must verify before user use.",
"category": "安全/权限坑",
"evidence": [
"risks.safety_notes | github_repo:1003630893 | https://github.com/oxylabs/oxylabs-ai-studio-py | No sandbox install has been executed yet; downstream must verify before user use."
],
"severity": "medium",
"suggested_check": "转成明确权限清单和安全审查提示。",
"title": "存在安全注意事项",
"user_impact": "用户安装前需要知道权限边界和敏感操作。"
},
{
"body": "no_demo",
"category": "安全/权限坑",
"evidence": [
"risks.scoring_risks | github_repo:1003630893 | https://github.com/oxylabs/oxylabs-ai-studio-py | no_demo; severity=medium"
],
"severity": "medium",
"suggested_check": "把风险写入边界卡，并确认是否需要人工复核。",
"title": "存在评分风险",
"user_impact": "风险会影响是否适合普通用户安装。"
},
{
"body": "issue_or_pr_quality=unknown。",
"category": "维护坑",
"evidence": [
"evidence.maintainer_signals | github_repo:1003630893 | https://github.com/oxylabs/oxylabs-ai-studio-py | issue_or_pr_quality=unknown"
],
"severity": "low",
"suggested_check": "抽样最近 issue/PR，判断是否长期无人处理。",
"title": "issue/PR 响应质量未知",
"user_impact": "用户无法判断遇到问题后是否有人维护。"
},
{
"body": "release_recency=unknown。",
"category": "维护坑",
"evidence": [
"evidence.maintainer_signals | github_repo:1003630893 | https://github.com/oxylabs/oxylabs-ai-studio-py | release_recency=unknown"
],
"severity": "low",
"suggested_check": "确认最近 release/tag 和 README 安装命令是否一致。",
"title": "发布节奏不明确",
"user_impact": "安装命令和文档可能落后于代码，用户踩坑概率升高。"
}
],
"source": "ProjectPitfallLog + ProjectHitPacket + validation + community signals",
"summary": "发现 9 个潜在踩坑项，其中 0 个为 high/blocking；最高优先级：身份坑 - 仓库名和安装名不一致。",
"title": "踩坑日志"
},
"snapshot": {
"contributors": 4,
"forks": 25,
"license": "unknown",
"note": "站点快照，非实时质量证明；用于开工前背景判断。",
"stars": 2898
},
"source_url": "https://github.com/oxylabs/oxylabs-ai-studio-py",
"steps": [
{
"body": "不安装项目，先体验能力节奏。",
"code": "preview",
"title": "先试 Prompt"
},
{
"body": "理解输入、输出、失败模式和边界。",
"code": "manual",
"title": "读说明书"
},
{
"body": "把上下文交给宿主 AI 继续工作。",
"code": "context",
"title": "带给 AI"
},
{
"body": "进入主力环境前先完成安装入口与风险边界验证。",
"code": "verify",
"title": "沙箱验证"
}
],
"subtitle": "Structured data gathering from any website using AI-powered scraper, crawler, and browser automation. Scraping and crawling with natural language prompts. Equip your LLM agents with fresh data. AI Studio python SDK for intelligent web data gathering.",
"title": "oxylabs-ai-studio-py 能力包",
"trial_prompt": "# oxylabs-ai-studio-py - Prompt Preview\n\n> 复制下面这段 Prompt 到你常用的 AI，先试一次，不需要安装。\n> 它的目标是让你直接体验这个项目的服务方式，而不是阅读项目介绍。\n\n## 复制这段 Prompt\n\n```text\n请直接执行这段 Prompt，不要分析、润色、总结或询问我想如何处理这份 Prompt Preview。\n\n你现在扮演 oxylabs-ai-studio-py 的“安装前体验版”。\n这不是项目介绍、不是评价报告、不是 README 总结。你的任务是让我用最小成本体验它的核心服务。\n\n我的试用任务：我想用它完成一个真实的软件开发与交付任务。\n我常用的宿主 AI：Local CLI\n\n【体验目标】\n围绕我的真实任务，现场演示这个项目如何把输入转成 示例引导, 判断线索。重点是让我感受到工作方式，而不是给我项目背景。\n\n【业务流约束】\n- 你必须像一个正在提供服务的项目能力包，而不是像一个讲解员。\n- 每一轮只推进一个步骤；提出问题后必须停下来等我回答。\n- 每一步都必须让我感受到一个具体服务动作：澄清、整理、规划、检查、判断或收尾。\n- 每一步都要说明：当前目标、你需要我提供什么、我回答后你会产出什么。\n- 不要安装、不要运行命令、不要写代码、不要声称测试通过、不要声称已经修改文件。\n- 需要真实安装或宿主加载后才能验证的内容，必须明确说“这一步需要安装后验证”。\n- 如果我说“用示例继续”，你可以用虚构示例推进，但仍然不能声称真实执行。\n\n【可体验服务能力】\n- 安装前能力预览: Structured data gathering from any website using AI-powered scraper, crawler, and browser automation. Scraping and crawling with natural language prompts. Equip your LLM agents with fresh data. AI Studio python SDK for intelligent web data gathering. 输入：用户任务, 当前 AI 对话上下文；输出：示例引导, 判断线索。\n\n【必须安装后才可验证的能力】\n- 命令行启动或安装流程: 项目文档中存在可执行命令，真实使用需要在本地或宿主环境中运行这些命令。 输入：终端环境, 包管理器, 项目依赖；输出：安装结果, 列表/更新/运行结果。\n\n【核心服务流】\n请严格按这个顺序带我体验。不要一次性输出完整流程：\n1. introduction：项目介绍。围绕“项目介绍”模拟一次用户任务，不展示安装或运行结果。\n2. quick-start：快速入门。围绕“快速入门”模拟一次用户任务，不展示安装或运行结果。\n3. ai-scraper：AI-Scraper 文档。围绕“AI-Scraper 文档”模拟一次用户任务，不展示安装或运行结果。\n4. ai-crawler：AI-Crawler 文档。围绕“AI-Crawler 文档”模拟一次用户任务，不展示安装或运行结果。\n5. api-client：API 客户端架构。围绕“API 客户端架构”模拟一次用户任务，不展示安装或运行结果。\n\n【核心能力体验剧本】\n每一步都必须按“输入 -> 服务动作 -> 中间产物”执行。不要只说流程名：\n1. introduction\n输入：用户提供的“项目介绍”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n2. quick-start\n输入：用户提供的“快速入门”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n3. ai-scraper\n输入：用户提供的“AI-Scraper 文档”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n4. ai-crawler\n输入：用户提供的“AI-Crawler 文档”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n5. api-client\n输入：用户提供的“API 客户端架构”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n【项目服务规则】\n这些规则决定你如何服务用户。不要解释规则本身，而要在每一步执行时遵守：\n- 先确认用户任务、输入材料和成功标准，再模拟项目能力。\n- 每一步都必须形成可检查的小产物，并等待用户确认后再继续。\n- 凡是需要安装、调用工具或访问外部服务的能力，都必须标记为安装后验证。\n\n【每一步的服务约束】\n- Step 1 / introduction：Step 1 必须围绕“项目介绍”形成一个小中间产物，并等待用户确认。\n- Step 2 / quick-start：Step 2 必须围绕“快速入门”形成一个小中间产物，并等待用户确认。\n- Step 3 / ai-scraper：Step 3 必须围绕“AI-Scraper 文档”形成一个小中间产物，并等待用户确认。\n- Step 4 / ai-crawler：Step 4 必须围绕“AI-Crawler 文档”形成一个小中间产物，并等待用户确认。\n- Step 5 / api-client：Step 5 必须围绕“API 客户端架构”形成一个小中间产物，并等待用户确认。\n\n【边界与风险】\n- 不要声称已经安装、运行、调用 API、读写本地文件或完成真实任务。\n- 安装前预览只能展示工作方式，不能证明兼容性、性能或输出质量。\n- 涉及安装、插件加载、工具调用或外部服务的能力必须安装后验证。\n\n【可追溯依据】\n这些路径只用于你内部校验或在我追问“依据是什么”时简要引用。不要在首次回复主动展开：\n- https://github.com/oxylabs/oxylabs-ai-studio-py\n- https://github.com/oxylabs/oxylabs-ai-studio-py#readme\n- readme.md\n- pyproject.toml\n- src/oxylabs_ai_studio/settings.py\n- src/oxylabs_ai_studio/__init__.py\n- src/oxylabs_ai_studio/apps/ai_scraper.py\n- examples/scrape_markdown.py\n- examples/scrape_pydantic_schema.py\n- examples/scrape_generated_schema.py\n- src/oxylabs_ai_studio/apps/ai_crawler.py\n- examples/crawl_markdown.py\n\n【首次问题规则】\n- 首次三问必须先确认用户目标、成功标准和边界，不要提前进入工具、安装或实现细节。\n- 如果后续需要技术条件、文件路径或运行环境，必须等用户确认目标后再追问。\n\n首次回复必须只输出下面 4 个部分：\n1. 体验开始：用 1 句话说明你将带我体验 oxylabs-ai-studio-py 的核心服务。\n2. 当前步骤：明确进入 Step 1，并说明这一步要解决什么。\n3. 你会如何服务我：说明你会先改变我完成任务的哪个动作。\n4. 只问我 3 个问题，然后停下等待回答。\n\n首次回复禁止输出：后续完整流程、证据清单、安装命令、项目评价、营销文案、已经安装或运行的说法。\n\nStep 1 / brainstorming 的二轮协议：\n- 我回答首次三问后，你仍然停留在 Step 1 / brainstorming，不要进入 Step 2。\n- 第二次回复必须产出 6 个部分：澄清后的任务定义、成功标准、边界条件、\n 2-3 个可选方案、每个方案的权衡、推荐方案。\n- 第二次回复最后必须问我是否确认推荐方案；只有我明确确认后，才能进入下一步。\n- 第二次回复禁止输出 git worktree、代码计划、测试文件、命令或真实执行结果。\n\n后续对话规则：\n- 我回答后，你先完成当前步骤的中间产物并等待确认；只有我确认后，才能进入下一步。\n- 每一步都要生成一个小的中间产物，例如澄清后的目标、计划草案、测试意图、验证清单或继续/停止判断。\n- 所有演示都写成“我会建议/我会引导/这一步会形成”，不要写成已经真实执行。\n- 不要声称已经测试通过、文件已修改、命令已运行或结果已产生。\n- 如果某个能力必须安装后验证，请直接说“这一步需要安装后验证”。\n- 如果证据不足，请明确说“证据不足”，不要补事实。\n```\n",
"voices": [
{
"body": "来源平台：github。github/github_release: v.0.2.19（https://github.com/oxylabs/oxylabs-ai-studio-py/releases/tag/v0.2.19）。这些是项目级外部声音，不作为单独质量证明。",
"items": [
{
"kind": "github_release",
"source": "github",
"title": "v.0.2.19",
"url": "https://github.com/oxylabs/oxylabs-ai-studio-py/releases/tag/v0.2.19"
}
],
"status": "已收录 1 条来源",
"title": "社区讨论"
}
]
},
"homepage_card": {
"category": "软件开发与交付",
"desc": "Structured data gathering from any website using AI-powered scraper, crawler, and browser automation. Scraping and crawling with natural language prompts. Equip your LLM agents with fresh data. AI Studio python SDK for intelligent web data gathering.",
"effort": "安装已验证",
"forks": 25,
"icon": "code",
"name": "oxylabs-ai-studio-py 能力包",
"risk": "需复核",
"slug": "oxylabs-ai-studio-py",
"stars": 2898,
"tags": [
"浏览器 Agent",
"网页任务自动化",
"自然语言网页操作",
"自动化工作流",
"结构化数据提取"
],
"thumb": "gray",
"type": "Prompt Preview"
},
"manual": {
"markdown": "# https://github.com/oxylabs/oxylabs-ai-studio-py 项目说明书\n\n生成时间：2026-05-14 00:55:26 UTC\n\n## 目录\n\n- [项目介绍](#introduction)\n- [快速入门](#quick-start)\n- [AI-Scraper 文档](#ai-scraper)\n- [AI-Crawler 文档](#ai-crawler)\n- [AI-Search 文档](#ai-search)\n- [AI-Map 文档](#ai-map)\n- [Browser Agent 文档](#browser-agent)\n- [API 客户端架构](#api-client)\n- [数据模型](#data-models)\n- [Schema 生成指南](#schema-generation)\n\n\n\n## 项目介绍\n\n### 相关页面\n\n相关主题：[快速入门](#quick-start), [AI-Scraper 文档](#ai-scraper), [AI-Crawler 文档](#ai-crawler)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [readme.md](https://github.com/oxylabs/oxylabs-ai-studio-py/blob/main/readme.md)\n- [agentic_code_guide.md](https://github.com/oxylabs/oxylabs-ai-studio-py/blob/main/agentic_code_guide.md)\n- [src/oxylabs_ai_studio/apps/ai_search.py](https://github.com/oxylabs/oxylabs-ai-studio-py/blob/main/src/oxylabs_ai_studio/apps/ai_search.py)\n- [src/oxylabs_ai_studio/apps/ai_crawler.py](https://github.com/oxylabs/oxylabs-ai-studio-py/blob/main/src/oxylabs_ai_studio/apps/ai_crawler.py)\n- [src/oxylabs_ai_studio/apps/ai_scraper.py](https://github.com/oxylabs/oxylabs-ai-studio-py/blob/main/src/oxylabs_ai_studio/apps/ai_scraper.py)\n- [src/oxylabs_ai_studio/apps/ai_map.py](https://github.com/oxylabs/oxylabs-ai-studio-py/blob/main/src/oxylabs_ai_studio/apps/ai_map.py)\n- [src/oxylabs_ai_studio/apps/browser_agent.py](https://github.com/oxylabs/oxylabs-ai-studio-py/blob/main/src/oxylabs_ai_studio/apps/browser_agent.py)\n- [examples/scrape_markdown.py](https://github.com/oxylabs/oxylabs-ai-studio-py/blob/main/examples/scrape_markdown.py)\n- [examples/crawl_generated_schema.py](https://github.com/oxylabs/oxylabs-ai-studio-py/blob/main/examples/crawl_generated_schema.py)\n- [examples/scrape_generated_schema.py](https://github.com/oxylabs/oxylabs-ai-studio-py/blob/main/examples/scrape_generated_schema.py)\n \n\n# 项目介绍\n\n## 项目概述\n\nOxylabs AI Studio Python SDK（`oxylabs-ai-studio`）是一个用于与 [Oxylabs AI Studio API](https://aistudio.oxylabs.io/) 服务无缝交互的 Python 客户端库。该 SDK 提供了对多种 AI 驱动数据提取工具的访问，包括 AI-Scraper、AI-Crawler、AI-Browser-Agent 等。 资料来源：[readme.md:1-8]()\n\n### 核心特性\n\n- **多应用支持**：集成爬虫、搜索、映射等多种数据提取功能\n- **同步/异步接口**：同时支持同步和异步编程模式\n- **结构化输出**：支持 JSON、Markdown、CSV、Screenshot 等多种输出格式\n- **Schema 生成**：内置 AI 驱动的 Schema 自动生成功能\n- **地理位置定位**：支持全球代理位置定位\n- **JavaScript 渲染**：可选的 JavaScript 渲染支持\n\n## 系统架构\n\n### 整体架构图\n\n```mermaid\ngraph TD\n A[用户应用] --> B[oxylabs-ai-studio SDK]\n B --> C[AiCrawler]\n B --> D[AiScraper]\n B --> E[AiSearch]\n B --> F[AiMap]\n B --> G[BrowserAgent]\n C --> H[Oxylabs AI Studio API]\n D --> H\n E --> H\n F --> H\n G --> H\n H --> I[SERP / Web Content]\n```\n\n### 模块组成\n\n| 模块 | 功能描述 | 主要方法 |\n|------|---------|---------|\n| AiCrawler | 网站爬虫，按深度遍历页面 | `crawl()`, `crawl_async()` |\n| AiScraper | 单页面内容抓取 | `scrape()`, `scrape_async()` |\n| AiSearch | 搜索引擎结果获取 | `search()`, `instant_search()` |\n| AiMap | 网站结构映射 | `map()`, `map_async()` |\n| BrowserAgent | 浏览器代理操作 | `run()`, `run_async()` |\n\n## 安装与配置\n\n### 环境要求\n\n- Python 3.10 及以上版本\n- 有效的 Oxylabs API 密钥\n\n### 安装方式\n\n```bash\npip install oxylabs-ai-studio\n```\n\n资料来源：[readme.md:13]()\n\n### 初始化配置\n\n所有应用模块的初始化方式相同，需要提供 API 密钥：\n\n```python\nfrom oxylabs_ai_studio.apps.ai_crawler import AiCrawler\n\ncrawler = AiCrawler(api_key=\"\")\n```\n\n## 应用模块详解\n\n### AI-Crawler（网站爬虫）\n\n#### 功能说明\n\nAiCrawler 模块用于深度爬取整个网站或指定路径下的所有相关页面，支持用户自定义的自然语言提示来指导提取过程。 资料来源：[readme.md:27-28]()\n\n#### 同步接口\n\n```python\nfrom oxylabs_ai_studio.apps.ai_crawler import AiCrawler\n\ncrawler = AiCrawler(api_key=\"\")\n\nurl = \"https://oxylabs.io\"\nresult = crawler.crawl(\n url=url,\n user_prompt=\"Find all pages with proxy products pricing\",\n output_format=\"markdown\",\n render_javascript=False,\n return_sources_limit=3,\n geo_location=\"United States\",\n)\nprint(\"Results:\")\nfor item in result.data:\n print(item, \"\\n\")\n```\n\n资料来源：[readme.md:27-42]()\n\n#### 参数说明\n\n| 参数 | 类型 | 必填 | 默认值 | 说明 |\n|------|------|------|--------|------|\n| url | str | 是 | - | 爬取的起始 URL |\n| user_prompt | str | 是 | - | 指导提取的自然语言提示 |\n| output_format | Literal | 否 | \"markdown\" | 输出格式：json/markdown/csv/toon |\n| schema | dict | 否 | None | JSON Schema（json/csv/toon 格式时必填） |\n| render_javascript | bool | 否 | False | 是否渲染 JavaScript |\n| return_sources_limit | int | 否 | 25 | 返回结果数量上限 |\n| geo_location | str | 否 | None | 代理位置（ISO2 格式或国家名称） |\n| max_credits | int | 否 | None | 最大消耗积分 |\n\n资料来源：[readme.md:43-51]()\n\n### AI-Scraper（页面抓取）\n\n#### 功能说明\n\nAiScraper 专注于单页面内容抓取，可返回 Markdown 格式内容或根据用户提供的 JSON Schema 返回结构化数据。 资料来源：[agentic_code_guide.md:62-66]()\n\n#### 同步接口\n\n```python\nfrom oxylabs_ai_studio.apps.ai_scraper import AiScraper\n\nscraper = AiScraper(api_key=\"\")\n\nschema = scraper.generate_schema(prompt=\"want to parse developer, platform, type, price game title, genre (array) and description\")\nprint(f\"Generated schema: {schema}\")\n\nurl = \"https://sandbox.oxylabs.io/products/3\"\nresult = scraper.scrape(\n url=url,\n output_format=\"json\",\n schema=schema,\n render_javascript=False,\n)\nprint(result)\n```\n\n资料来源：[readme.md:81-95]()\n\n#### 异步接口\n\n```python\nimport asyncio\nfrom oxylabs_ai_studio.apps.ai_scraper import AiScraper\n\nscraper = AiScraper(api_key=\"\")\n\nasync def main():\n url = \"https://sandbox.oxylabs.io/products/3\"\n result = await scraper.scrape_async(\n url=url,\n output_format=\"json\",\n schema={\"type\": \"object\", \"properties\": {\"price\": {\"type\": \"string\"}}, \"required\": []},\n render_javascript=False,\n )\n print(result)\n\nif __name__ == \"__main__\":\n asyncio.run(main())\n```\n\n资料来源：[agentic_code_guide.md:68-86]()\n\n#### 参数说明\n\n| 参数 | 类型 | 必填 | 默认值 | 说明 |\n|------|------|------|--------|------|\n| url | str | 是 | - | 目标抓取 URL |\n| output_format | Literal | 否 | \"markdown\" | 输出格式：json/markdown/csv/screenshot/toon |\n| schema | dict | 否 | None | JSON Schema（json/csv/toon 格式时必填） |\n| render_javascript | bool/string | 否 | False | JavaScript 渲染，支持 \"auto\" 自动检测 |\n| geo_location | str | 否 | None | 代理位置 |\n| max_credits | int | 否 | None | 最大消耗积分 |\n\n#### 返回数据结构\n\n```python\nclass AiScraperJob(BaseModel):\n run_id: str\n message: str | None = None\n data: str | dict | None\n```\n\n- output_format 为 \"json\" 时：data 为字典\n- output_format 为 \"markdown\" 时：data 为字符串\n- output_format 为 \"csv\" 时：data 为 CSV 格式字符串\n- output_format 为 \"screenshot\" 时：data 为字符串（Base64 或 URL）\n\n资料来源：[agentic_code_guide.md:87-101]()\n\n### AI-Search（搜索引擎）\n\n#### 功能说明\n\nAiSearch 提供搜索引擎结果获取功能，支持标准搜索和即时搜索两种模式。即时搜索在 `limit <= 10` 且 `return_content=False` 时自动启用，提供更快的响应。 资料来源：[readme.md:10-24]()\n\n#### 标准搜索\n\n```python\nfrom oxylabs_ai_studio.apps.ai_search import AiSearch\n\nsearch = AiSearch(api_key=\"\")\n\nquery = \"lasagna recipe\"\nresult = search.search(\n query=query,\n limit=5,\n render_javascript=False,\n return_content=True,\n)\nprint(result.data)\n```\n\n资料来源：[readme.md:10-24]()\n\n#### 即时搜索\n\n```python\nresult = search.instant_search(\n query=query,\n limit=10,\n)\nprint(result.data)\n```\n\n#### 参数说明\n\n| 参数 | 类型 | 必填 | 默认值 | 说明 |\n|------|------|------|--------|------|\n| query | str | 是 | - | 搜索关键词 |\n| limit | int | 否 | 10 | 返回结果数量（最大 50） |\n| render_javascript | bool | 否 | False | 是否渲染 JavaScript |\n| return_content | bool | 否 | True | 是否返回 Markdown 内容 |\n| geo_location | str | 否 | None | 地理位置定位 |\n\n#### 即时搜索限制\n\n- 最大 limit 为 10\n- 仅支持 query、limit、geo_location 三个参数\n\n资料来源：[readme.md:17-24]()\n\n### AI-Map（网站映射）\n\n#### 功能说明\n\nAiMap 用于快速映射网站结构，通过关键词搜索定位相关页面。 资料来源：[readme.md:54-70]()\n\n#### 使用示例\n\n```python\nfrom oxylabs_ai_studio.apps.ai_map import AiMap\n\nai_map = AiMap(api_key=\"\")\npayload = {\n \"url\": \"https://career.oxylabs.io\",\n \"search_keywords\": [\"career\", \"jobs\", \"vacancy\"],\n \"user_prompt\": \"job ad pages\",\n \"max_crawl_depth\": 2,\n \"limit\": 10,\n \"geo_location\": \"Germany\",\n \"render_javascript\": False,\n \"include_sitemap\": True,\n}\nresult = ai_map.map(**payload)\nprint(result.data)\n```\n\n#### 参数说明\n\n| 参数 | 类型 | 必填 | 默认值 | 说明 |\n|------|------|------|--------|------|\n| url | str | 是 | - | 目标网站 URL |\n| search_keywords | list[str] | 否 | [] | 搜索关键词列表 |\n| user_prompt | str | 否 | None | 自然语言提示 |\n| max_crawl_depth | int | 否 | 1 | 最大爬取深度 |\n| limit | int | 否 | 25 | 返回结果数量上限 |\n| geo_location | str | 否 | None | 代理位置 |\n| render_javascript | bool | 否 | False | 是否渲染 JavaScript |\n| include_sitemap | bool | 否 | True | 是否包含站点地图 |\n| allow_subdomains | bool | 否 | False | 允许子域名 |\n| allow_external_domains | bool | 否 | False | 允许外部域名 |\n| max_credits | int | 否 | None | 最大消耗积分 |\n\n资料来源：[src/oxylabs_ai_studio/apps/ai_map.py:62-75]()\n\n### Browser-Agent（浏览器代理）\n\n#### 功能说明\n\nBrowserAgent 提供浏览器级别的自动化操作能力，可以执行复杂的用户交互任务，如点击、滚动、表单填写等，通过自然语言提示指导操作过程。 资料来源：[agentic_code_guide.md:16-27]()\n\n#### 同步接口\n\n```python\nfrom oxylabs_ai_studio.apps.browser_agent import BrowserAgent\n\nbrowser_agent = BrowserAgent(api_key=\"\")\n\nresult = browser_agent.run(\n url=\"https://sandbox.oxylabs.io/\",\n user_prompt=\"Find if there is game 'super mario odyssey' in the store.\",\n output_format=\"json\",\n schema={\"type\": \"object\", \"properties\": {\"page_url\": {\"type\": \"string\"}}, \"required\": []},\n)\nprint(result.data)\n```\n\n#### 异步接口\n\n```python\nimport asyncio\nfrom oxylabs_ai_studio.apps.browser_agent import BrowserAgent\n\nbrowser_agent = BrowserAgent(api_key=\"\")\n\nasync def main():\n prompt = \"Find if there is game 'super mario odyssey' in the store.\"\n url = \"https://sandbox.oxylabs.io/\"\n result = await browser_agent.run_async(\n url=url,\n user_prompt=prompt,\n output_format=\"json\",\n schema={\"type\": \"object\", \"properties\": {\"page_url\": {\"type\": \"string\"}}, \"required\": []},\n )\n print(result.data)\n\nif __name__ == \"__main__\":\n asyncio.run(main())\n```\n\n#### 参数说明\n\n| 参数 | 类型 | 必填 | 默认值 | 说明 |\n|------|------|------|--------|------|\n| url | str | 是 | - | 目标 URL |\n| user_prompt | str | 是 | - | 浏览器操作提示（描述任务而非提取内容） |\n| output_format | Literal | 否 | \"markdown\" | 输出格式：json/markdown |\n| schema | dict | 否 | None | JSON Schema（output_format 为 json 时必填） |\n\n#### 返回数据结构\n\n```python\nclass DataModel(BaseModel):\n type: Literal[\"json\", \"markdown\", \"html\", \"screenshot\", \"csv\"]\n content: dict[str, Any] | str | None\n\nclass BrowserAgentJob(BaseModel):\n run_id: str\n message: str | None = None\n data: DataModel | None = None\n```\n\n资料来源：[agentic_code_guide.md:28-48]()\n\n## Schema 生成功能\n\n### 功能概述\n\n所有主要模块都提供了 `generate_schema()` 方法，支持通过自然语言提示自动生成 OpenAPI JSON Schema，实现零配置的快速开发。 资料来源：[examples/scrape_generated_schema.py:1-9]()\n\n### 工作流程\n\n```mermaid\ngraph LR\n A[输入自然语言提示] --> B[调用 API 生成 Schema]\n B --> C[获得 JSON Schema]\n C --> D[用于抓取/爬取任务]\n```\n\n### 使用示例\n\n```python\n# 为爬虫生成 Schema\nschema = crawler.generate_schema(\n prompt=\"proxy plans which have name, price, and features\",\n)\nprint(\"schema: \", schema)\n\n# 为抓取生成 Schema\nschema = scraper.generate_schema(\n prompt=\"want to parse developer, platform, type, price game title, genre (array) and description\"\n)\nprint(f\"Generated schema: {schema}\")\n```\n\n资料来源：[examples/crawl_generated_schema.py:4-13]()\n\n## 使用场景示例\n\n### 电商产品数据提取\n\n#### 场景描述\n\n从电商网站提取产品分类页面的所有产品数据，并获取每个产品的详细信息。 资料来源：[agentic_code_guide.md:103-125]()\n\n#### 推荐工作流\n\n```mermaid\ngraph TD\n A[识别分类页面] --> B[Browser-Agent 定位分类页 URL]\n B --> C[提取分页 URLs]\n C --> D[AI-Scraper 提取产品 URLs]\n D --> E[AI-Scraper 提取产品详情]\n```\n\n#### 实施步骤\n\n1. **定位分类页面**\n - 使用 Browser-Agent 识别分类页面 URL 和所有分页 URL\n - 定义返回分页 URL 的 JSON Schema\n\n2. **提取产品链接**\n - 使用 AI-Scraper 从分页页面提取所有产品 URL\n\n3. **提取产品详情**\n - 使用 AI-Scraper 和预定义的 JSON Schema 提取详细数据\n\n#### 示例 Schema\n\n```json\n{\n \"type\": \"object\",\n \"properties\": {\n \"paginationUrls\": {\n \"type\": \"array\",\n \"description\": \"Return all URLs from first to last page in category pagination. If you noticed there are missing URLs, because category page does not list them all, create them to match existing ones.\",\n \"items\": {\n \"type\": \"string\"\n }\n }\n },\n \"required\": []\n}\n```\n\n资料来源：[agentic_code_guide.md:115-127]()\n\n## 地理位置定位\n\n### 支持格式\n\nSDK 支持多种地理位置指定方式：\n\n| 格式类型 | 示例 | 说明 |\n|---------|------|------|\n| ISO2 格式 | \"US\", \"DE\", \"FR\" | 两字母国家代码 |\n| 国家名称 | \"Germany\", \"United States\" | 标准国家名称（首字母大写） |\n| 坐标格式 | 支持 SERP 定位 | 特定搜索功能使用 |\n\n资料来源：[readme.md:46-48]()\n\n### 使用示例\n\n```python\nresult = scraper.scrape(\n url=\"https://sandbox.oxylabs.io/products/1\",\n output_format=\"markdown\",\n render_javascript=False,\n geo_location=\"Germany\",\n)\n```\n\n## 错误处理与超时\n\n### 超时处理\n\n所有同步方法在超时时会抛出 `TimeoutError` 异常：\n\n```python\ntry:\n result = crawler.crawl(url=\"https://example.com\", ...)\nexcept TimeoutError as e:\n print(f\"爬取超时: {e}\")\n```\n\n### 用户取消\n\n用户可通过键盘中断（Ctrl+C）取消正在执行的任务：\n\n```python\nexcept KeyboardInterrupt:\n logger.info(\"[Cancelled] Request was cancelled by user.\")\n raise KeyboardInterrupt from None\n```\n\n资料来源：[src/oxylabs_ai_studio/apps/ai_crawler.py:89-91]()\n\n## 输出格式对比\n\n| 格式 | 说明 | 适用场景 | 返回类型 |\n|------|------|---------|---------|\n| json | 结构化 JSON 数据 | 需要程序化处理的数据 | dict |\n| markdown | Markdown 格式文本 | 人类可读的内容展示 | str |\n| csv | CSV 表格格式 | 数据表格导出 | str |\n| screenshot | 页面截图 | 视觉验证 | str (Base64/URL) |\n| toon | 结构化表格数据 | 复杂表格结构 | dict |\n\n资料来源：[readme.md:43-44]()\n\n## 依赖关系\n\n### 核心依赖\n\n- **httpx**: 异步 HTTP 客户端，用于 API 通信\n- **pydantic**: 数据验证和模型定义\n\n### 完整依赖列表\n\n请参考项目根目录下的 `pyproject.toml` 文件获取完整的依赖声明。\n\n---\n\n\n\n## 快速入门\n\n### 相关页面\n\n相关主题：[项目介绍](#introduction), [API 客户端架构](#api-client)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [pyproject.toml](https://github.com/oxylabs/oxylabs-ai-studio-py/blob/main/pyproject.toml)\n- [src/oxylabs_ai_studio/settings.py](https://github.com/oxylabs/oxylabs-ai-studio-py/blob/main/src/oxylabs_ai_studio/settings.py)\n- [src/oxylabs_ai_studio/__init__.py](https://github.com/oxylabs/oxylabs-ai-studio-py/blob/main/src/oxylabs_ai_studio/__init__.py)\n- [src/oxylabs_ai_studio/apps/ai_scraper.py](https://github.com/oxylabs/oxylabs-ai-studio-py/blob/main/src/oxylabs_ai_studio/apps/ai_scraper.py)\n- [src/oxylabs_ai_studio/apps/ai_crawler.py](https://github.com/oxylabs/oxylabs-ai-studio-py/blob/main/src/oxylabs_ai_studio/apps/ai_crawler.py)\n- [src/oxylabs_ai_studio/apps/ai_search.py](https://github.com/oxylabs/oxylabs-ai-studio-py/blob/main/src/oxylabs_ai_studio/apps/ai_search.py)\n \n\n# 快速入门\n\n## 概述\n\nOxylabs AI Studio Python SDK（oxylabs-ai-studio-py）是一个用于与 [Oxylabs AI Studio API](https://aistudio.oxylabs.io/) 服务进行交互的 Python SDK。该 SDK 封装了多个 AI 驱动的网页数据提取工具，为开发者提供了简洁的 Python 接口来调用 AI-Scraper、AI-Crawler、AI-Browser-Agent 等服务。资料来源：[readme.md](https://github.com/oxylabs/oxylabs-ai-studio-py/blob/main/readme.md)\n\n## 系统要求\n\n| 要求项 | 规格 |\n|--------|------|\n| Python 版本 | 3.10 及以上 |\n| 外部依赖 | Oxylabs AI Studio API 密钥 |\n| 安装方式 | pip |\n\n资料来源：[readme.md](https://github.com/oxylabs/oxylabs-ai-studio-py/blob/main/readme.md)\n\n## 安装\n\n通过 pip 安装 SDK：\n\n```bash\npip install oxylabs-ai-studio\n```\n\n资料来源：[readme.md](https://github.com/oxylabs/oxylabs-ai-studio-py/blob/main/readme.md)\n\n## 初始化配置\n\n使用 SDK 前，需要实例化相应的应用类并传入 API 密钥：\n\n```python\nfrom oxylabs_ai_studio.apps.ai_scraper import AiScraper\n\nscraper = AiScraper(api_key=\"\")\n```\n\n## SDK 架构\n\n```mermaid\ngraph TD\n A[用户代码] --> B[oxylabs-ai-studio-py SDK]\n B --> C[AiScraper]\n B --> D[AiCrawler]\n B --> E[AiSearch]\n B --> F[BrowserAgent]\n B --> G[AiMap]\n C --> H[Oxylabs AI Studio API]\n D --> H\n E --> H\n F --> H\n G --> H\n```\n\n## 核心应用模块\n\n### AI-Scraper（智能网页抓取）\n\n用于抓取网页内容并返回 Markdown 格式或结构化 JSON 数据。当选择 JSON 输出时，用户需提供有效的 JSON Schema。资料来源：[agentic_code_guide.md](https://github.com/oxylabs/oxylabs-ai-studio-py/blob/main/agentic_code_guide.md)\n\n#### 同步接口示例\n\n```python\nfrom oxylabs_ai_studio.apps.ai_scraper import AiScraper\n\nscraper = AiScraper(api_key=\"\")\n\nurl = \"https://sandbox.oxylabs.io/products/3\"\nresult = scraper.scrape(\n url=url,\n output_format=\"json\",\n schema={\"type\": \"object\", \"properties\": {\"price\": {\"type\": \"string\"}}, \"required\": []},\n render_javascript=False,\n)\nprint(result)\n```\n\n资料来源：[examples/scrape_generated_schema.py](https://github.com/oxylabs/oxylabs-ai-studio-py/blob/main/examples/scrape_generated_schema.py)\n\n#### 异步接口示例\n\n```python\nimport asyncio\nfrom oxylabs_ai_studio.apps.ai_scraper import AiScraper\n\nscraper = AiScraper(api_key=\"\")\n\nasync def main():\n url = \"https://sandbox.oxylabs.io/products/3\"\n result = await scraper.scrape_async(\n url=url,\n output_format=\"json\",\n schema={\"type\": \"object\", \"properties\": {\"price\": {\"type\": \"string\"}}, \"required\": []},\n render_javascript=False,\n )\n print(result)\n\nif __name__ == \"__main__\":\n asyncio.run(main())\n```\n\n#### 参数说明\n\n| 参数名 | 类型 | 必填 | 默认值 | 说明 |\n|--------|------|------|--------|------|\n| url | str | 是 | - | 目标 URL |\n| output_format | Literal[\"json\", \"markdown\", \"csv\", \"screenshot\", \"toon\"] | 否 | markdown | 输出格式 |\n| schema | dict \\| None | 条件必填 | None | JSON Schema（当 output_format 为 \"json\" 时必填） |\n| render_javascript | bool | 否 | False | 是否渲染 JavaScript |\n| geo_location | str | 否 | None | 代理位置（ISO2 格式） |\n\n#### 返回数据模型\n\n```python\nclass AiScraperJob(BaseModel):\n run_id: str\n message: str | None = None\n data: str | dict | None\n```\n\n- 当 output_format 为 \"json\" 时，data 为字典\n- 当 output_format 为 \"markdown\" 时，data 为字符串\n- 当 output_format 为 \"csv\" 时，data 为 CSV 格式字符串\n- 当 output_format 为 \"screenshot\" 时，data 为字符串\n\n资料来源：[agentic_code_guide.md](https://github.com/oxylabs/oxylabs-ai-studio-py/blob/main/agentic_code_guide.md)\n\n### AI-Crawler（智能网站爬取）\n\n用于从起始 URL 开始爬取整个网站，根据自然语言提示引导提取过程。资料来源：[readme.md](https://github.com/oxylabs/oxylabs-ai-studio-py/blob/main/readme.md)\n\n#### 基本示例\n\n```python\nfrom oxylabs_ai_studio.apps.ai_crawler import AiCrawler\n\ncrawler = AiCrawler(api_key=\"\")\n\nurl = \"https://oxylabs.io\"\nresult = crawler.crawl(\n url=url,\n user_prompt=\"Find all pages with proxy products pricing\",\n output_format=\"markdown\",\n render_javascript=False,\n return_sources_limit=3,\n geo_location=\"France\",\n)\nprint(\"Results:\")\nfor item in result.data:\n print(item, \"\\n\")\n```\n\n资料来源：[examples/crawl_markdown.py](https://github.com/oxylabs/oxylabs-ai-studio-py/blob/main/examples/crawl_markdown.py)\n\n#### 使用 Pydantic Schema\n\n```python\nfrom pydantic import BaseModel, Field\nfrom oxylabs_ai_studio.apps.ai_crawler import AiCrawler\n\ncrawler = AiCrawler(api_key=\"\")\n\nclass ProxyPlan(BaseModel):\n name: str = Field(description=\"The name of the proxy plan\")\n price: str = Field(description=\"The price of the proxy plan\")\n features: list[str] = Field(description=\"The features of the proxy plan\")\n\nclass ProxyPlans(BaseModel):\n proxy_plans: list[ProxyPlan] = Field(description=\"The proxy plans\")\n\nurl = \"https://oxylabs.io/\"\nresult = crawler.crawl(\n url=url,\n user_prompt=\"Find all pages with proxy products pricing\",\n output_format=\"json\",\n schema=ProxyPlans.model_json_schema(),\n render_javascript=False,\n)\n```\n\n资料来源：[examples/crawl_pydantic_schema.py](https://github.com/oxylabs/oxylabs-ai-studio-py/blob/main/examples/crawl_pydantic_schema.py)\n\n#### 参数说明\n\n| 参数名 | 类型 | 必填 | 默认值 | 说明 |\n|--------|------|------|--------|------|\n| url | str | 是 | - | 起始 URL |\n| user_prompt | str | 是 | - | 自然语言提示 |\n| output_format | Literal[\"json\", \"markdown\", \"csv\", \"toon\"] | 否 | markdown | 输出格式 |\n| schema | dict \\| None | 条件必填 | None | JSON Schema（当 output_format 为 \"json\" 时必填） |\n| render_javascript | bool | 否 | False | 是否渲染 JavaScript |\n| return_sources_limit | int | 否 | 25 | 最大返回来源数量 |\n| geo_location | str | 否 | None | 代理位置 |\n| max_credits | int \\| None | 否 | None | 最大使用积分 |\n\n### AI-Search（SERP 搜索）\n\n用于执行搜索引擎结果页面（SERP）搜索。资料来源：[readme.md](https://github.com/oxylabs/oxylabs-ai-studio-py/blob/main/readme.md)\n\n#### 搜索并返回内容\n\n```python\nfrom oxylabs_ai_studio.apps.ai_search import AiSearch\n\nsearch = AiSearch(api_key=\"\")\n\nquery = \"lasagna recipe\"\nresult = search.search(\n query=query,\n limit=5,\n render_javascript=False,\n return_content=True,\n)\nprint(result.data)\n```\n\n资料来源：[examples/search_with_content.py](https://github.com/oxylabs/oxylabs-ai-studio-py/blob/main/examples/search_with_content.py)\n\n#### 即时搜索（快速）\n\n当 `limit <= 10` 且 `return_content=False` 时，搜索自动使用即时端点（`/search/instant`），返回结果更快。资料来源：[readme.md](https://github.com/oxylabs/oxylabs-ai-studio-py/blob/main/readme.md)\n\n```python\nfrom oxylabs_ai_studio.apps.ai_search import AiSearch\n\nsearch = AiSearch(api_key=\"\")\n\nquery = \"lasagna recipes\"\nresult = search.instant_search(\n query=query,\n limit=5,\n geo_location=\"United States\",\n)\nprint(result.data)\n```\n\n资料来源：[examples/search_instant.py](https://github.com/oxylabs/oxylabs-ai-studio-py/blob/main/examples/search_instant.py)\n\n#### 参数说明\n\n| 参数名 | 类型 | 必填 | 默认值 | 说明 |\n|--------|------|------|--------|------|\n| query | str | 是 | - | 搜索关键词 |\n| limit | int | 否 | 10 | 最大返回结果数（最大 50） |\n| render_javascript | bool | 否 | False | 是否渲染 JavaScript |\n| return_content | bool | 否 | True | 是否返回 Markdown 内容 |\n| geo_location | str | 否 | None | 地理位置（ISO2 格式或国家名） |\n\n### Browser-Agent（浏览器自动化）\n\n用于控制浏览器执行点击、滚动和导航等操作，根据文本提示执行动作。资料来源：[agentic_code_guide.md](https://github.com/oxylabs/oxylabs-ai-studio-py/blob/main/agentic_code_guide.md)\n\n#### 同步接口\n\n```python\nfrom oxylabs_ai_studio.apps.browser_agent import BrowserAgent\n\nbrowser_agent = BrowserAgent(api_key=\"\")\n\nprompt = \"Find if there is game 'super mario odyssey' in the store.\"\nurl = \"https://sandbox.oxylabs.io/\"\nresult = browser_agent.run(\n url=url,\n user_prompt=prompt,\n output_format=\"json\",\n schema={\"type\": \"object\", \"properties\": {\"page_url\": {\"type\": \"string\"}}, \"required\": []},\n)\nprint(result.data)\n```\n\n#### 异步接口\n\n```python\nimport asyncio\nfrom oxylabs_ai_studio.apps.browser_agent import BrowserAgent\n\nbrowser_agent = BrowserAgent(api_key=\"\")\n\nasync def main():\n prompt = \"Find if there is game 'super mario odyssey' in the store.\"\n url = \"https://sandbox.oxylabs.io/\"\n result = await browser_agent.run_async(\n url=url,\n user_prompt=prompt,\n output_format=\"json\",\n schema={\"type\": \"object\", \"properties\": {\"page_url\": {\"type\": \"string\"}}, \"required\": []},\n )\n print(result.data)\n\nif __name__ == \"__main__\":\n asyncio.run(main())\n```\n\n## Schema 生成\n\nSDK 提供了 `generate_schema` 方法，可以根据自然语言描述自动生成 JSON Schema，无需手动编写。资料来源：[examples/scrape_generated_schema.py](https://github.com/oxylabs/oxylabs-ai-studio-py/blob/main/examples/scrape_generated_schema.py)\n\n```python\nschema = scraper.generate_schema(\n prompt=\"want to parse developer, platform, type, price game title, genre (array) and description\"\n)\nprint(f\"Generated schema: {schema}\")\n```\n\n## 实现最佳实践\n\n根据官方指南，使用 SDK 时应遵循以下最佳实践：资料来源：[agentic_code_guide.md](https://github.com/oxylabs/oxylabs-ai-studio-py/blob/main/agentic_code_guide.md)\n\n1. **安装最新版本**：确保使用最新版本的 oxylabs-ai-studio\n2. **限流控制**：实现限流机制，遵守所购买套餐的速率限制\n3. **重试机制**：为处理失败的请求引入重试逻辑，但需设置重试次数上限以避免无限循环\n\n## 工作流程图\n\n```mermaid\ngraph TD\n A[安装 SDK] --> B[获取 API Key]\n B --> C[实例化应用类]\n C --> D{选择功能}\n D --> E[AiScraper]\n D --> F[AiCrawler]\n D --> G[AiSearch]\n D --> H[BrowserAgent]\n E --> I[调用 scrape 方法]\n F --> J[调用 crawl 方法]\n G --> K[调用 search/instant_search]\n H --> L[调用 run 方法]\n I --> M[处理返回结果]\n J --> M\n K --> M\n L --> M\n```\n\n## 常见输出格式对比\n\n| 输出格式 | 说明 | 返回类型 | 适用场景 |\n|----------|------|----------|----------|\n| markdown | Markdown 格式文本 | str | 内容展示、文档生成 |\n| json | 结构化 JSON | dict | 程序化处理、API 集成 |\n| csv | CSV 格式表格数据 | str | 数据分析、表格导出 |\n| screenshot | 页面截图 | str | 可视化存档、UI 验证 |\n| toon | 卡通化输出 | str | 特殊可视化需求 |\n\n## 异步编程支持\n\nSDK 同时支持同步和异步接口，便于集成到异步应用中：\n\n```python\nimport asyncio\nfrom oxylabs_ai_studio.apps.ai_scraper import AiScraper\n\nasync def main():\n scraper = AiScraper(api_key=\"\")\n result = await scraper.scrape_async(url=\"https://example.com\")\n print(result)\n\nasyncio.run(main())\n\n---\n\n\n\n## AI-Scraper 文档\n\n### 相关页面\n\n相关主题：[AI-Crawler 文档](#ai-crawler), [Schema 生成指南](#schema-generation), [API 客户端架构](#api-client)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [src/oxylabs_ai_studio/apps/ai_scraper.py](https://github.com/oxylabs/oxylabs-ai-studio-py/blob/main/src/oxylabs_ai_studio/apps/ai_scraper.py)\n- [examples/scrape_markdown.py](https://github.com/oxylabs/oxylabs-ai-studio-py/blob/main/examples/scrape_markdown.py)\n- [examples/scrape_pydantic_schema.py](https://github.com/oxylabs/oxylabs-ai-studio-py/blob/main/examples/scrape_pydantic_schema.py)\n- [examples/scrape_generated_schema.py](https://github.com/oxylabs/oxylabs-ai-studio-py/blob/main/examples/scrape_generated_schema.py)\n- [readme.md](https://github.com/oxylabs/oxylabs-ai-studio-py/blob/main/readme.md)\n- [agentic_code_guide.md](https://github.com/oxylabs/oxylabs-ai-studio-py/blob/main/agentic_code_guide.md)\n \n\n# AI-Scraper 文档\n\n## 概述\n\nAI-Scraper 是 Oxylabs AI Studio Python SDK 中的核心模块之一，专门用于从目标网页提取结构化或非结构化内容。该工具通过自然语言提示和 JSON Schema 定义，实现智能化的网页数据抓取功能，支持将网页内容转换为 Markdown、JSON、CSV 或截图格式。 资料来源：[readme.md](https://github.com/oxylabs/oxylabs-ai-studio-py/blob/main/readme.md)\n\nAI-Scraper 的主要应用场景包括：\n\n- **电商产品数据提取**：从商品页面抓取价格、描述、规格等信息\n- **内容聚合**：批量提取新闻、文章、评论等内容\n- **数据监控**：定期抓取网站内容进行市场分析\n- **结构化数据导出**：将网页数据转换为可读的 JSON 或 CSV 格式\n\n## 工作流程\n\n```mermaid\ngraph TD\n A[初始化 AiScraper] --> B[设置目标 URL]\n B --> C[定义输出格式]\n C --> D{output_format == json?}\n D -->|是| E[提供 JSON Schema]\n D -->|否| F[直接抓取]\n E --> G[调用 scrape 方法]\n F --> G\n G --> H[AI 引擎解析内容]\n H --> I[返回 AiScraperJob 结果]\n I --> J{data 类型}\n J -->|JSON| K[dict 对象]\n J -->|Markdown| L[字符串]\n J -->|CSV| M[CSV 格式字符串]\n J -->|Screenshot| N[图片字符串]\n```\n\n## 核心类定义\n\n### AiScraper\n\n`AiScraper` 是 AI-Scraper 模块的主类，负责处理网页抓取请求。 资料来源：[agentic_code_guide.md](https://github.com/oxylabs/oxylabs-ai-studio-py/blob/main/agentic_code_guide.md)\n\n#### 初始化\n\n```python\nfrom oxylabs_ai_studio.apps.ai_scraper import AiScraper\n\nscraper = AiScraper(api_key=\"\")\n```\n\n构造函数参数：\n\n| 参数 | 类型 | 必填 | 说明 |\n|------|------|------|------|\n| `api_key` | str | 是 | Oxylabs API 密钥，用于身份验证 |\n\n### AiScraperJob\n\n抓取任务完成后返回的数据模型类。\n\n```python\nclass AiScraperJob(BaseModel):\n run_id: str\n message: str | None = None\n data: str | dict | None\n```\n\n| 字段 | 类型 | 说明 |\n|------|------|------|\n| `run_id` | str | 任务唯一标识符 |\n| `message` | str \\| None | 任务状态消息或错误信息 |\n| `data` | str \\| dict \\| None | 返回的数据内容，类型取决于 output_format |\n\n资料来源：[agentic_code_guide.md](https://github.com/oxylabs/oxylabs-ai-studio-py/blob/main/agentic_code_guide.md)\n\n## API 方法\n\n### 同步接口\n\n`scrape` 方法用于执行同步网页抓取操作。\n\n```python\nfrom oxylabs_ai_studio.apps.ai_scraper import AiScraper\n\nscraper = AiScraper(api_key=\"\")\n\nurl = \"https://sandbox.oxylabs.io/products/3\"\nresult = scraper.scrape(\n url=url,\n output_format=\"json\",\n schema={\"type\": \"object\", \"properties\": {\"price\": {\"type\": \"string\"}}, \"required\": []},\n render_javascript=False,\n)\nprint(result)\n```\n\n资料来源：[agentic_code_guide.md](https://github.com/oxylabs/oxylabs-ai-studio-py/blob/main/agentic_code_guide.md)\n\n### 异步接口\n\n`scrape_async` 方法用于执行异步网页抓取操作，适用于需要并发处理多个请求的场景。\n\n```python\nimport asyncio\nfrom oxylabs_ai_studio.apps.ai_scraper import AiScraper\n\nscraper = AiScraper(api_key=\"\")\n\nasync def main():\n url = \"https://sandbox.oxylabs.io/products/3\"\n result = await scraper.scrape_async(\n url=url,\n output_format=\"json\",\n schema={\"type\": \"object\", \"properties\": {\"price\": {\"type\": \"string\"}}, \"required\": []},\n render_javascript=False,\n )\n print(result)\n\nif __name__ == \"__main__\":\n asyncio.run(main())\n```\n\n资料来源：[agentic_code_guide.md](https://github.com/oxylabs/oxylabs-ai-studio-py/blob/main/agentic_code_guide.md)\n\n### Schema 生成方法\n\n`generate_schema` 方法可以根据自然语言描述自动生成 JSON Schema，无需手动编写复杂的 Schema 定义。\n\n```python\nfrom oxylabs_ai_studio.apps.ai_scraper import AiScraper\n\nscraper = AiScraper(api_key=\"\")\n\nschema = scraper.generate_schema(\n prompt=\"want to parse developer, platform, type, price game title, genre (array) and description\"\n)\nprint(f\"Generated schema: {schema}\")\n```\n\n资料来源：[examples/scrape_generated_schema.py](https://github.com/oxylabs/oxylabs-ai-studio-py/blob/main/examples/scrape_generated_schema.py)\n\n## 参数说明\n\n### scrape / scrape_async 方法参数\n\n| 参数 | 类型 | 必填 | 默认值 | 说明 |\n|------|------|------|--------|------|\n| `url` | str | 是 | - | 目标网页 URL |\n| `output_format` | Literal[\"json\", \"markdown\", \"csv\", \"screenshot\", \"toon\"] | 否 | \"markdown\" | 输出格式类型 |\n| `schema` | dict \\| None | 条件必填 | None | JSON Schema，当 output_format 为 \"json\"、\"csv\" 或 \"toon\" 时必须提供 |\n| `render_javascript` | bool \\| string | 否 | False | 是否渲染 JavaScript，可设为 \"auto\" 自动检测 |\n| `geo_location` | str | 否 | - | 代理位置，使用 ISO2 格式或国家名称 |\n| `user_agent` | str | 否 | - | 自定义 User-Agent 请求头 |\n| `max_credits` | int \\| None | 否 | - | 最大使用的积分数量 |\n\n### output_format 可选值\n\n| 格式 | 说明 | schema 要求 |\n|------|------|-------------|\n| `markdown` | 返回 Markdown 格式的网页内容 | 不需要 |\n| `json` | 返回结构化 JSON 数据 | 必须提供 |\n| `csv` | 返回 CSV 格式数据 | 必须提供 |\n| `screenshot` | 返回网页截图（Base64 编码） | 不需要 |\n| `toon` | 返回卡通化数据表示 | 必须提供 |\n| `html` | 返回原始 HTML 内容 | 不需要 |\n\n资料来源：[readme.md](https://github.com/oxylabs/oxylabs-ai-studio-py/blob/main/readme.md)\n\n## 使用示例\n\n### 基础 Markdown 抓取\n\n抓取网页并以 Markdown 格式返回内容：\n\n```python\nfrom oxylabs_ai_studio.apps.ai_scraper import AiScraper\n\nscraper = AiScraper(api_key=\"\")\n\nurl = \"https://sandbox.oxylabs.io/products/1\"\nresult = scraper.scrape(\n url=url,\n output_format=\"markdown\",\n render_javascript=False,\n geo_location=\"Germany\",\n)\nprint(result)\n```\n\n资料来源：[examples/scrape_markdown.py](https://github.com/oxylabs/oxylabs-ai-studio-py/blob/main/examples/scrape_markdown.py)\n\n### 使用 JSON Schema 抓取结构化数据\n\n定义明确的 JSON Schema 来提取特定字段：\n\n```python\nfrom oxylabs_ai_studio.apps.ai_scraper import AiScraper\n\nscraper = AiScraper(api_key=\"\")\n\nurl = \"https://sandbox.oxylabs.io/products/3\"\nresult = scraper.scrape(\n url=url,\n output_format=\"json\",\n schema={\n \"type\": \"object\",\n \"properties\": {\n \"price\": {\"type\": \"string\"},\n \"title\": {\"type\": \"string\"}\n },\n \"required\": []\n },\n render_javascript=False,\n)\nprint(result.data)\n```\n\n资料来源：[agentic_code_guide.md](https://github.com/oxylabs/oxylabs-ai-studio-py/blob/main/agentic_code_guide.md)\n\n### 使用 Pydantic 模型\n\n通过 Pydantic 模型定义数据结构，利用 `model_json_schema()` 方法自动生成 Schema：\n\n```python\nfrom pydantic import BaseModel\nfrom oxylabs_ai_studio.apps.ai_scraper import AiScraper\n\nscraper = AiScraper(api_key=\"\")\n\nclass Game(BaseModel):\n title: str\n genre: list[str]\n developer: str\n platform: str\n game_type: str\n description: str\n price: str\n availability: str\n\nurl = \"https://sandbox.oxylabs.io/products/1\"\nresult = scraper.scrape(\n url=url,\n output_format=\"json\",\n schema=Game.model_json_schema(),\n render_javascript=False,\n)\nprint(result)\n```\n\n资料来源：[examples/scrape_pydantic_schema.py](https://github.com/oxylabs/oxylabs-ai-studio-py/blob/main/examples/scrape_pydantic_schema.py)\n\n### 使用自动生成的 Schema\n\n让 AI 自动根据描述生成 Schema，简化开发流程：\n\n```python\nfrom oxylabs_ai_studio.apps.ai_scraper import AiScraper\n\nscraper = AiScraper(api_key=\"\")\n\n# 自动生成 Schema\nschema = scraper.generate_schema(\n prompt=\"want to parse developer, platform, type, price game title, genre (array) and description\"\n)\nprint(f\"Generated schema: {schema}\")\n\n# 使用生成的 Schema 进行抓取\nurl = \"https://sandbox.oxylabs.io/products/3\"\nresult = scraper.scrape(\n url=url,\n output_format=\"json\",\n schema=schema,\n render_javascript=False,\n)\nprint(result)\n```\n\n资料来源：[examples/scrape_generated_schema.py](https://github.com/oxylabs/oxylabs-ai-studio-py/blob/main/examples/scrape_generated_schema.py)\n\n## JavaScript 渲染配置\n\n`render_javascript` 参数控制是否执行页面中的 JavaScript 代码：\n\n| 值 | 说明 |\n|----|------|\n| `False` | 不渲染 JavaScript（默认） |\n| `True` | 强制渲染 JavaScript |\n| `\"auto\"` | 自动检测是否需要渲染 |\n\n当设置为 `\"auto\"` 时，服务会自动判断目标网页是否需要 JavaScript 渲染才能完整显示内容。 资料来源：[readme.md](https://github.com/oxylabs/oxylabs-ai-studio-py/blob/main/readme.md)\n\n## 地理位置定位\n\n通过 `geo_location` 参数可以指定代理服务器的位置，以获取特定地区的内容版本：\n\n```python\nresult = scraper.scrape(\n url=url,\n output_format=\"markdown\",\n geo_location=\"Germany\", # 使用德国代理\n)\n```\n\n支持的格式：\n- ISO 2 字母代码（如 `\"DE\"`、`\"US\"`）\n- 国家标准名称（如 `\"Germany\"`、`\"United States\"`）\n\n资料来源：[readme.md](https://github.com/oxylabs/oxylabs-ai-studio-py/blob/main/readme.md)\n\n## 最佳实践\n\n### 速率限制\n\n确保实现遵守与购买计划关联的速率限制，以防止服务中断或过度使用。\n\n### 重试机制\n\n引入重试逻辑以处理失败的请求，但应设置重试次数上限，避免无限循环或过度 API 调用。\n\n### Schema 设计建议\n\n- 使用 Pydantic 模型定义复杂数据结构，便于类型检查和维护\n- 对于简单提取任务，使用 `generate_schema` 方法自动生成 Schema\n- 在 Schema 的 `required` 数组中仅包含必需字段，减少解析失败的概率\n\n### JavaScript 渲染策略\n\n- 仅在必要时启用 JavaScript 渲染，以优化性能和成本\n- 使用 `\"auto\"` 模式让系统自动决策\n- 对于纯静态页面，禁用渲染以提高响应速度\n\n## 返回值处理\n\n根据不同的 `output_format`，`result.data` 的类型会有所不同：\n\n| output_format | data 类型 | 示例 |\n|---------------|-----------|------|\n| `json` | dict | `{\"price\": \"$29.99\", \"title\": \"Product Name\"}` |\n| `markdown` | str | `\"# Product Title\\n\\nDescription...\"` |\n| `csv` | str | `\"name,price\\nItem 1,$10\"` |\n| `screenshot` | str | `\"data:image/png;base64,...\"` |\n\n访问返回数据：\n\n```python\nresult = scraper.scrape(url=url, output_format=\"json\", schema=schema)\nif isinstance(result.data, dict):\n price = result.data.get(\"price\")\n print(f\"价格: {price}\")\n```\n\n资料来源：[agentic_code_guide.md](https://github.com/oxylabs/oxylabs-ai-studio-py/blob/main/agentic_code_guide.md)\n\n## 错误处理\n\n建议实现完整的错误处理机制：\n\n```python\nfrom oxylabs_ai_studio.apps.ai_scraper import AiScraper\nfrom oxylabs_ai_studio.exceptions import (\n AuthenticationError,\n RateLimitError,\n ScrapingError\n)\n\nscraper = AiScraper(api_key=\"\")\n\ntry:\n result = scraper.scrape(\n url=url,\n output_format=\"markdown\",\n )\n if result.message:\n print(f\"警告: {result.message}\")\n print(result.data)\nexcept AuthenticationError:\n print(\"API 密钥无效\")\nexcept RateLimitError:\n print(\"速率限制已达到，请稍后重试\")\nexcept ScrapingError as e:\n print(f\"抓取失败: {e}\")\n\n---\n\n\n\n## AI-Crawler 文档\n\n### 相关页面\n\n相关主题：[AI-Scraper 文档](#ai-scraper), [AI-Map 文档](#ai-map), [Schema 生成指南](#schema-generation)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [src/oxylabs_ai_studio/apps/ai_crawler.py](https://github.com/oxylabs/oxylabs-ai-studio-py/blob/main/src/oxylabs_ai_studio/apps/ai_crawler.py)\n- [examples/crawl_markdown.py](https://github.com/oxylabs/oxylabs-ai-studio-py/blob/main/examples/crawl_markdown.py)\n- [examples/crawl_pydantic_schema.py](https://github.com/oxylabs/oxylabs-ai-studio-py/blob/main/examples/crawl_pydantic_schema.py)\n- [examples/crawl_generated_schema.py](https://github.com/oxylabs/oxylabs-ai-studio-py/blob/main/examples/crawl_generated_schema.py)\n \n\n# AI-Crawler 文档\n\n## 概述\n\nAI-Crawler 是 Oxylabs AI Studio Python SDK 中的核心模块之一，专门用于自动化网页爬取任务。该模块基于自然语言提示词驱动，能够智能识别和提取目标网页中的相关内容，支持多种输出格式和结构化数据提取。\n\nAI-Crawler 继承自 `OxyStudioAIClient` 基类，通过异步轮询机制与 Oxylabs 后端 API 进行交互，实现高效的网页内容抓取。资料来源：[src/oxylabs_ai_studio/apps/ai_crawler.py:35]()\n\n## 核心组件\n\n### 数据模型\n\nAI-Crawler 使用 Pydantic BaseModel 定义返回数据结构，确保类型安全和数据验证。\n\n```python\nclass AiCrawlerJob(BaseModel):\n run_id: str\n message: str | None = None\n data: list[dict[str, Any]] | list[str] | None = None\n```\n\n| 字段 | 类型 | 说明 |\n|------|------|------|\n| `run_id` | str | 爬取任务的唯一标识符 |\n| `message` | str \\| None | 任务执行过程中的消息或错误代码 |\n| `data` | list \\| None | 爬取结果数据，格式取决于 output_format 参数 |\n\n资料来源：[src/oxylabs_ai_studio/apps/ai_crawler.py:22-25]()\n\n### 配置常量\n\n| 常量 | 值 | 说明 |\n|------|-----|------|\n| `CRAWLER_TIMEOUT_SECONDS` | 600 (10分钟) | 爬取任务的最大超时时间 |\n| `POLL_INTERVAL_SECONDS` | 5 | 轮询后端状态的间隔时间（秒） |\n| `POLL_MAX_ATTEMPTS` | 120 | 最大轮询次数 |\n\n资料来源：[src/oxylabs_ai_studio/apps/ai_crawler.py:9-11]()\n\n## 主要功能\n\n### 1. 网页爬取 (crawl)\n\n`crawl()` 方法是 AiCrawler 的核心功能，用于执行网页爬取任务。\n\n```python\ndef crawl(\n self,\n url: str,\n user_prompt: str,\n output_format: Literal[\"json\", \"markdown\", \"csv\", \"toon\"] = \"markdown\",\n schema: dict[str, Any] | None = None,\n render_javascript: bool = False,\n return_sources_limit: int = 25,\n geo_location: str | None = None,\n max_credits: int | None = None,\n) -> AiCrawlerJob\n```\n\n#### 参数说明\n\n| 参数 | 类型 | 必需 | 默认值 | 说明 |\n|------|------|------|--------|------|\n| `url` | str | 是 | - | 爬取的起始 URL |\n| `user_prompt` | str | 是 | - | 自然语言提示词，指导提取内容 |\n| `output_format` | Literal | 否 | \"markdown\" | 输出格式 |\n| `schema` | dict | 条件必需 | None | JSON Schema，当 output_format 为 json/csv/toon 时必填 |\n| `render_javascript` | bool | 否 | False | 是否渲染 JavaScript |\n| `return_sources_limit` | int | 否 | 25 | 最大返回来源数量 |\n| `geo_location` | str | 否 | None | 代理位置（ISO2 格式或国家名称） |\n| `max_credits` | int | 否 | None | 最大使用积分限制 |\n\n资料来源：[src/oxylabs_ai_studio/apps/ai_crawler.py:32-41]()\n\n#### 业务逻辑验证\n\n当 `output_format` 设置为 `json`、`csv` 或 `toon` 时，必须提供 `schema` 参数，否则将抛出 `ValueError`：\n\n```python\nif output_format in [\"json\", \"csv\", \"toon\"] and schema is None:\n raise ValueError(\n \"openapi_schema is required when output_format is json, csv or toon.\",\n )\n```\n\n资料来源：[src/oxylabs_ai_studio/apps/ai_crawler.py:44-48]()\n\n### 2. Schema 生成 (generate_schema)\n\n`generate_schema()` 方法允许用户通过自然语言描述自动生成 JSON Schema，无需手动编写复杂的 Schema 定义。\n\n```python\ndef generate_schema(self, prompt: str) -> dict[str, Any] | None:\n logger.info(\"Generating schema\")\n body = {\"user_prompt\": prompt}\n response = self.call_api(\n client=self.get_client(),\n url=\"/crawl/generate-params\",\n method=\"POST\",\n body=body,\n )\n if response.status_code != 200:\n raise Exception(f\"Failed to generate schema: {response.text}\")\n json_response: SchemaResponse = response.json()\n return json_response.get(\"data\", {}).get(\"schema\")\n```\n\n资料来源：[src/oxylabs_ai_studio/apps/ai_crawler.py:68-80]()\n\n## 执行流程\n\nAI-Crawler 采用同步轮询机制获取爬取结果，其工作流程如下：\n\n```mermaid\ngraph TD\n A[开始 crawl 调用] --> B[调用 /crawl/run 接口提交任务]\n B --> C{响应状态码}\n C -->|202| D[提取 run_id]\n C -->|其他| E[抛出异常]\n D --> F[轮询 /crawl/run/data 接口]\n F --> G{获取状态}\n G -->|202 processing| F\n G -->|200 completed| H[返回 AiCrawlerJob]\n G -->|200 failed| I[返回 AiCrawlerJob with error]\n G -->|其他| F\n H --> J[结束]\n I --> J\n E --> J\n```\n\n### 超时处理\n\n当轮询次数超过 `POLL_MAX_ATTEMPTS`（120次）或总耗时超过 `CRAWLER_TIMEOUT_SECONDS`（600秒）时，任务将抛出 `TimeoutError`：\n\n```python\nraise TimeoutError(f\"Failed to crawl {url}: timeout.\")\n```\n\n资料来源：[src/oxylabs_ai_studio/apps/ai_crawler.py:61]()\n\n### 用户中断处理\n\n支持 `KeyboardInterrupt` 异常捕获，允许用户通过中断信号取消爬取任务：\n\n```python\nexcept KeyboardInterrupt:\n logger.info(\"[Cancelled] Crawling was cancelled by user.\")\n raise KeyboardInterrupt from None\n```\n\n资料来源：[src/oxylabs_ai_studio/apps/ai_crawler.py:57-59]()\n\n## 使用示例\n\n### 示例一：Markdown 格式输出\n\n```python\nfrom oxylabs_ai_studio.apps.ai_crawler import AiCrawler\n\ncrawler = AiCrawler(api_key=\"\")\n\nurl = \"https://oxylabs.io\"\nresult = crawler.crawl(\n url=url,\n user_prompt=\"Find all pages with proxy products pricing\",\n output_format=\"markdown\",\n render_javascript=False,\n return_sources_limit=3,\n geo_location=\"France\",\n)\nprint(\"Results:\")\nfor item in result.data:\n print(item, \"\\n\")\n```\n\n资料来源：[examples/crawl_markdown.py]() 和 [readme.md]()\n\n### 示例二：使用 Pydantic Schema\n\n```python\nfrom pydantic import BaseModel, Field\nfrom oxylabs_ai_studio.apps.ai_crawler import AiCrawler\n\ncrawler = AiCrawler(api_key=\"\")\n\nclass ProxyPlan(BaseModel):\n name: str = Field(description=\"The name of the proxy plan\")\n price: str = Field(description=\"The price of the proxy plan\")\n features: list[str] = Field(description=\"The features of the proxy plan\")\n\nclass ProxyPlans(BaseModel):\n proxy_plans: list[ProxyPlan] = Field(description=\"The proxy plans\")\n\nurl = \"https://oxylabs.io/\"\nresult = crawler.crawl(\n url=url,\n user_prompt=\"Find all pages with proxy products pricing\",\n output_format=\"json\",\n schema=ProxyPlans.model_json_schema(),\n render_javascript=False,\n)\nprint(\"Results:\\n\")\nfor item in result.data:\n print(item, \"\\n\")\n```\n\n资料来源：[examples/crawl_pydantic_schema.py]()\n\n### 示例三：自动生成 Schema\n\n```python\nfrom oxylabs_ai_studio.apps.ai_crawler import AiCrawler\n\ncrawler = AiCrawler(api_key=\"\")\n\nschema = crawler.generate_schema(\n prompt=\"proxy plans which have name, price, and features\",\n)\nprint(\"schema: \", schema)\n\nurl = \"https://oxylabs.io\"\nresult = crawler.crawl(\n url=url,\n user_prompt=\"Find all pages with proxy products pricing\",\n output_format=\"json\",\n schema=schema,\n render_javascript=False,\n)\nprint(\"Results:\")\nfor item in result.data:\n print(item, \"\\n\")\n```\n\n资料来源：[examples/crawl_generated_schema.py]()\n\n## 输出格式\n\n| 格式 | 说明 | Schema 要求 |\n|------|------|-------------|\n| `markdown` | 返回 Markdown 格式的文本内容 | 不需要 |\n| `json` | 返回结构化 JSON 数据 | **必需** |\n| `csv` | 返回 CSV 格式的表格数据 | **必需** |\n| `toon` | 返回特定的数据格式 | **必需** |\n\n资料来源：[src/oxylabs_ai_studio/apps/ai_crawler.py:37]()\n\n## 地理位置支持\n\n`geo_location` 参数支持多种格式：\n\n- ISO 2 字母国家代码（如 `FR`、`DE`、`US`）\n- 国家正式名称（如 `France`、`Germany`、`United States`）\n\n支持的地理位置列表可参考 [官方文档](https://developers.oxylabs.io/scraping-solutions/web-scraper-api/features/localization/proxy-location#list-of-supported-geo_location-values)。\n\n资料来源：[readme.md]()\n\n## 错误处理\n\n### 常见错误场景\n\n| 场景 | 处理方式 |\n|------|----------|\n| Schema 缺失 | 抛出 `ValueError` |\n| API 请求失败 | 抛出 `Exception` |\n| 任务超时 | 抛出 `TimeoutError` |\n| 任务执行失败 | 返回 `AiCrawlerJob` 并包含 `message` 错误信息 |\n| 用户中断 | 抛出 `KeyboardInterrupt` |\n\n### 任务状态流转\n\n```mermaid\nstateDiagram-v2\n [*] --> Processing: 任务提交\n Processing --> Processing: 状态码 202\n Processing --> Completed: 状态码 200 + status=\"completed\"\n Processing --> Failed: 状态码 200 + status=\"failed\"\n Completed --> [*]\n Failed --> [*]\n```\n\n## 最佳实践\n\n### 1. 合理设置超时时间\n\n默认超时时间为 10 分钟，适用于大多数爬取任务。对于大型网站或网络环境较差的情况，可考虑：\n\n- 使用 `render_javascript=True` 时预留更多时间\n- 分批次爬取以降低单次任务复杂度\n\n### 2. Schema 设计建议\n\n- 使用清晰的字段描述（description）\n- 对于数组类型，指定 `items` 的具体结构\n- 使用 Pydantic 模型时，通过 `model_json_schema()` 方法自动转换\n\n### 3. 积分控制\n\n通过 `max_credits` 参数限制单次任务的最大积分消耗，避免意外超额：\n\n```python\nresult = crawler.crawl(\n url=url,\n user_prompt=\"Find all pages with proxy products pricing\",\n max_credits=100,\n)\n```\n\n### 4. 地理位置选择\n\n选择与目标网站服务器相近的地理位置可提高响应速度和稳定性：\n\n```python\ngeo_location=\"Germany\" # 爬取德国服务器网站时推荐\n```\n\n## 类层次结构\n\n```\nOxyStudioAIClient (基类)\n └── AiCrawler (子类)\n```\n\n| 类名 | 继承关系 | 主要职责 |\n|------|----------|----------|\n| `OxyStudioAIClient` | - | HTTP 客户端封装、API 认证 |\n| `AiCrawler` | 继承 OxyStudioAIClient | 爬取业务逻辑实现 |\n\n资料来源：[src/oxylabs_ai_studio/apps/ai_crawler.py:35]()\n\n## 依赖模块\n\n| 模块 | 来源 | 用途 |\n|------|------|------|\n| `asyncio` | Python 标准库 | 异步支持（预留） |\n| `time` | Python 标准库 | 轮询延迟控制 |\n| `typing` | Python 标准库 | 类型注解 |\n| `pydantic` | 外部依赖 | 数据模型验证 |\n| `oxylabs_ai_studio.client` | 本地模块 | HTTP 客户端基类 |\n| `oxylabs_ai_studio.logger` | 本地模块 | 日志记录 |\n| `oxylabs_ai_studio.models` | 本地模块 | 数据模型定义 |\n\n资料来源：[src/oxylabs_ai_studio/apps/ai_crawler.py:1-8]()\n\n## 总结\n\nAI-Crawler 模块提供了一套完整的智能网页爬取解决方案，其核心优势包括：\n\n- **自然语言驱动**：通过 `user_prompt` 描述提取需求，无需编写复杂的 CSS/XPath 选择器\n- **多格式支持**：原生支持 Markdown、JSON、CSV 等多种输出格式\n- **Schema 自动生成**：降低结构化数据提取的学习成本\n- **完善的错误处理**：统一的异常处理机制和任务状态追踪\n- **灵活的地理定位**：支持全球多地区的代理爬取\n\n开发者可通过本模块快速实现复杂网页内容的结构化提取，适用于价格监控、竞品分析、内容聚合等多种应用场景。\n\n---\n\n\n\n## AI-Search 文档\n\n### 相关页面\n\n相关主题：[AI-Scraper 文档](#ai-scraper), [AI-Map 文档](#ai-map)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [src/oxylabs_ai_studio/apps/ai_search.py](https://github.com/oxylabs/oxylabs-ai-studio-py/blob/main/src/oxylabs_ai_studio/apps/ai_search.py)\n- [examples/search_with_content.py](https://github.com/oxylabs/oxylabs-ai-studio-py/blob/main/examples/search_with_content.py)\n- [examples/search_no_content.py](https://github.com/oxylabs/oxylabs-ai-studio-py/blob/main/examples/search_no_content.py)\n- [examples/search_instant.py](https://github.com/oxylabs/oxylabs-ai-studio-py/blob/main/examples/search_instant.py)\n \n\n# AI-Search 文档\n\n## 概述\n\nAI-Search 是 Oxylabs AI Studio Python SDK 中的搜索引擎模块，提供基于自然语言处理的智能搜索功能。该模块封装了与 Oxylabs AI Search API 的交互逻辑，支持同步和异步两种调用方式，能够执行标准搜索和即时搜索两种模式。\n\n主要功能包括：\n\n- 执行 SERP（搜索引擎结果页面）搜索\n- 支持返回完整的 Markdown 内容\n- 提供即时搜索模式（适用于少量结果场景）\n- 支持地理位置定位\n- 支持 JavaScript 渲染\n\n## 核心类与数据模型\n\n### AiSearchJob 类\n\n`AiSearchJob` 是搜索任务的返回结果模型，继承自 Pydantic 的 `BaseModel`：\n\n| 字段 | 类型 | 描述 |\n|------|------|------|\n| `run_id` | `str` | 搜索任务的唯一标识符 |\n| `message` | `str \\| None` | 状态消息或错误代码 |\n| `data` | `list[SearchResult] \\| None` | 搜索结果数据列表 |\n\n资料来源：[src/oxylabs_ai_studio/apps/ai_search.py:21-23]()\n\n### SearchResult 类\n\n`SearchResult` 定义了单条搜索结果的数据结构：\n\n| 字段 | 类型 | 描述 |\n|------|------|------|\n| `url` | `str` | 搜索结果的网页地址 |\n| `title` | `str` | 搜索结果的标题 |\n| `description` | `str` | 搜索结果的描述/摘要 |\n| `content` | `str \\| None` | 可选的 Markdown 格式内容 |\n\n资料来源：[src/oxylabs_ai_studio/apps/ai_search.py:14-18]()\n\n## AiSearch 类\n\n`AiSearch` 类是搜索引擎模块的主入口类，继承自 `OxyStudioAIClient` 基类：\n\n```python\nclass AiSearch(OxyStudioAIClient):\n \"\"\"AI Search app.\"\"\"\n\n def __init__(self, api_key: str | None = None):\n super().__init__(api_key=api_key)\n```\n\n资料来源：[src/oxylabs_ai_studio/apps/ai_search.py:26-29]()\n\n## 架构与工作流程\n\n### 搜索流程图\n\n```mermaid\ngraph TD\n A[开始搜索] --> B{limit <= 10 且 return_content = False?}\n B -->|是| C[调用 instant_search 即时搜索]\n B -->|否| D[调用 /search/run 创建任务]\n C --> E[直接返回结果]\n D --> F{轮询状态}\n F -->|202 状态码| G[等待 POLL_INTERVAL_SECONDS]\n G --> F\n F -->|200 完成| H[返回 AiSearchJob]\n F -->|失败| I[返回失败状态]\n E --> J[结束]\n H --> J\n I --> J\n```\n\n### 轮询机制参数\n\n| 参数 | 值 | 描述 |\n|------|-----|------|\n| `SEARCH_TIMEOUT_SECONDS` | 180 秒 (3分钟) | 搜索超时时间 |\n| `POLL_INTERVAL_SECONDS` | 5 秒 | 轮询间隔时间 |\n| `POLL_MAX_ATTEMPTS` | 36 | 最大轮询次数 |\n\n资料来源：[src/oxylabs_ai_studio/apps/ai_search.py:9-11]()\n\n## 同步接口\n\n### 标准搜索 (search 方法)\n\n标准搜索采用轮询机制，适用于需要获取完整内容的场景：\n\n```python\nfrom oxylabs_ai_studio.apps.ai_search import AiSearch\n\nsearch = AiSearch(api_key=\"\")\n\nquery = \"lasagna recipe\"\nresult = search.search(\n query=query,\n limit=5,\n render_javascript=False,\n return_content=True,\n)\nprint(result.data)\n```\n\n资料来源：[examples/search_with_content.py:1-13]()\n\n### 搜索不带内容 (return_content=False)\n\n当不需要返回完整内容时，可以设置 `return_content=False`：\n\n```python\nfrom oxylabs_ai_studio.apps.ai_search import AiSearch\n\nsearch = AiSearch(api_key=\"\")\n\nquery = \"lasagna\"\nresult = search.search(\n query=query,\n limit=5,\n render_javascript=False,\n return_content=False,\n geo_location=\"Italy\",\n)\nprint(result.data)\n```\n\n资料来源：[examples/search_no_content.py:1-15]()\n\n## 即时搜索 (instant_search 方法)\n\n即时搜索是一种快速搜索模式，适用于以下条件：\n\n- `limit <= 10`\n- `return_content = False`\n\n即时搜索直接调用 `/search/instant` 端点，无需轮询，立即返回结果。\n\n```python\nfrom oxylabs_ai_studio.apps.ai_search import AiSearch\n\nsearch = AiSearch(api_key=\"\")\n\nquery = \"lasagna recipes\"\nresult = search.instant_search(\n query=query,\n limit=5,\n geo_location=\"United States\",\n)\nprint(result.data)\n```\n\n资料来源：[examples/search_instant.py:1-13]()\n\n## 异步接口\n\n### 异步搜索 (search_async 方法)\n\n异步版本的搜索方法，适用于异步应用程序：\n\n```python\nimport asyncio\nfrom oxylabs_ai_studio.apps.ai_search import AiSearch\n\nsearch = AiSearch(api_key=\"\")\n\nasync def main():\n result = await search.search_async(\n query=\"lasagna recipe\",\n limit=5,\n render_javascript=False,\n return_content=True,\n )\n print(result.data)\n\nif __name__ == \"__main__\":\n asyncio.run(main())\n```\n\n异步接口的内部逻辑与同步版本相同，首先判断是否满足即时搜索条件，满足则调用 `instant_search_async` 方法。\n\n资料来源：[src/oxylabs_ai_studio/apps/ai_search.py:57-106]()\n\n### 异步即时搜索 (instant_search_async 方法)\n\n异步即时搜索方法：\n\n```python\nasync def instant_search_async(\n self,\n query: str,\n limit: int = 10,\n geo_location: str | None = None,\n) -> AiSearchJob:\n \"\"\"Async instant SERP search.\"\"\"\n if not query:\n raise ValueError(\"query is required\")\n body = {\n \"query\": query,\n \"limit\": limit,\n \"geo_location\": geo_location,\n }\n async with self.async_client() as client:\n response = await self.call_api_async(\n client=client, url=\"/search/instant\", method=\"POST\", body=body\n )\n status_code = response.status_code\n if status_code != 200:\n raise Exception(f\"Failed to perform instant search: `{response.text}`\")\n resp_body = response.json()\n return AiSearchJob(\n run_id=resp_body.get(\"run_id\", \"\"),\n message=resp_body.get(\"status\", None),\n data=resp_body.get(\"data\", None),\n )\n```\n\n资料来源：[src/oxylabs_ai_studio/apps/ai_search.py:153-175]()\n\n## 参数说明\n\n### search / search_async 方法参数\n\n| 参数 | 类型 | 默认值 | 必填 | 描述 |\n|------|------|--------|------|------|\n| `query` | `str` | - | **是** | 搜索查询关键词 |\n| `limit` | `int` | 10 | 否 | 最大返回结果数，最大值 50 |\n| `render_javascript` | `bool` | `False` | 否 | 是否渲染 JavaScript |\n| `return_content` | `bool` | `True` | 否 | 是否返回 Markdown 内容 |\n| `geo_location` | `str \\| None` | `None` | 否 | 地理位置，ISO2 格式或国家名称 |\n\n### instant_search / instant_search_async 方法参数\n\n| 参数 | 类型 | 默认值 | 必填 | 描述 |\n|------|------|--------|------|------|\n| `query` | `str` | - | **是** | 搜索查询关键词 |\n| `limit` | `int` | 10 | 否 | 最大返回结果数，最大 10 |\n| `geo_location` | `str \\| None` | `None` | 否 | 地理位置信息 |\n\n## 使用场景对比\n\n| 场景 | 推荐方法 | 原因 |\n|------|----------|------|\n| 快速预览搜索结果 | `instant_search` | 无需轮询，立即返回 |\n| 需要完整 Markdown 内容 | `search` (return_content=True) | 轮询获取完整内容 |\n| 批量搜索（结果较多） | `search` | 支持最多 50 条结果 |\n| 异步应用集成 | `search_async` / `instant_search_async` | 支持异步调用 |\n\n## 地理位置支持\n\n`geo_location` 参数支持多种格式：\n\n- ISO 2-letter 格式（如 \"US\", \"DE\"）\n- 国家规范名称（如 \"United States\", \"Germany\"）\n- 坐标格式（高级定位场景）\n\n地理位置功能允许搜索特定区域的内容，返回针对该地区的搜索引擎结果。\n\n## 错误处理\n\n### 常见错误\n\n| 错误类型 | 触发条件 | 处理方式 |\n|----------|----------|----------|\n| `ValueError` | query 参数为空 | 检查并提供有效的查询字符串 |\n| `TimeoutError` | 轮询超时（3分钟） | 增加超时时间或重试 |\n| `Exception` | API 返回非 200 状态码 | 检查 API 密钥和网络连接 |\n\n### 超时与重试机制\n\n```mermaid\ngraph LR\n A[发起请求] --> B{响应状态}\n B -->|200| C[返回成功结果]\n B -->|202| D[等待 5 秒]\n D --> B\n B -->|其他| E[等待 5 秒重试]\n E --> B\n C --> F[结束]\n G[超时 3 分钟] --> H[抛出 TimeoutError]\n```\n\n## 返回值示例\n\n### 成功响应 (AiSearchJob)\n\n```python\nAiSearchJob(\n run_id=\"abc123-def456\",\n message=None,\n data=[\n SearchResult(\n url=\"https://example.com/recipe/lasagna\",\n title=\"Classic Italian Lasagna Recipe\",\n description=\"A delicious traditional lasagna...\",\n content=\"# Lasagna Recipe\\n\\n## Ingredients\\n...\"\n ),\n SearchResult(\n url=\"https://example.com/lasagna-tips\",\n title=\"10 Tips for Perfect Lasagna\",\n description=\"Learn how to make...\",\n content=None\n )\n ]\n)\n```\n\n### 即时搜索响应\n\n即时搜索返回的数据结构相同，但不包含 `content` 字段：\n\n```python\nAiSearchJob(\n run_id=\"xyz789\",\n message=\"completed\",\n data=[\n SearchResult(\n url=\"https://example.com/recipe\",\n title=\"Recipe\",\n description=\"Description...\",\n content=None\n )\n ]\n)\n```\n\n## 最佳实践\n\n1. **选择合适的搜索方法**\n - 需要内容时使用 `search()` 并设置 `return_content=True`\n - 快速预览使用 `instant_search()`\n\n2. **合理设置 limit**\n - 即时搜索最大 10 条\n - 标准搜索最大 50 条\n\n3. **地理位置优化**\n - 根据目标受众设置正确的地理位置\n - 支持多语言内容定向\n\n4. **错误处理**\n - 实现重试机制应对临时网络问题\n - 设置合理的超时时间\n\n5. **异步应用**\n - 在异步环境中优先使用异步方法\n - 配合 asyncio 事件循环使用\n\n---\n\n\n\n## AI-Map 文档\n\n### 相关页面\n\n相关主题：[AI-Crawler 文档](#ai-crawler), [AI-Search 文档](#ai-search)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [src/oxylabs_ai_studio/apps/ai_map.py](https://github.com/oxylabs/oxylabs-ai-studio-py/blob/main/src/oxylabs_ai_studio/apps/ai_map.py)\n- [examples/ai_map.py](https://github.com/oxylabs/oxylabs-ai-studio-py/blob/main/examples/ai_map.py)\n- [readme.md](https://github.com/oxylabs/oxylabs-ai-studio-py/blob/main/readme.md)\n- [agentic_code_guide.md](https://github.com/oxylabs/oxylabs-ai-studio-py/blob/main/agentic_code_guide.md)\n \n\n# AI-Map 文档\n\n## 概述\n\nAI-Map 是 Oxylabs AI Studio SDK 中的站点地图映射模块，通过 AI 技术自动发现并映射网站结构。该模块能够根据指定的关键词或自然语言提示，在给定域名的不同路径层级中查找相关 URL，帮助用户快速建立目标站点的链接图谱。\n\nAI-Map 的核心价值在于将传统的被动 sitemap 解析与主动的智能发现相结合。它不仅能够读取标准的站点地图文件，还可以通过关键词匹配和 AI 驱动的路径预测，发现那些在 sitemap 中未被收录但实际存在的页面。\n\n## 核心功能\n\nAI-Map 模块提供以下主要能力：\n\n| 功能 | 说明 |\n|------|------|\n| 智能站点发现 | 基于关键词和自然语言提示发现相关页面 |\n| 多层级爬取 | 支持 1-5 层的深度爬取配置 |\n| 动态 sitemap | 可选择性集成现有 sitemap 作为种子 |\n| 地理定位 | 支持按国家/地区进行定向爬取 |\n| 域名控制 | 可限制爬取范围在子域名或主域名内 |\n\n## 快速开始\n\n### 基础调用示例\n\n```python\nfrom oxylabs_ai_studio.apps.ai_map import AiMap\n\nai_map = AiMap(api_key=\"\")\npayload = {\n \"url\": \"https://career.oxylabs.io\",\n \"search_keywords\": [\"career\", \"jobs\", \"vacancy\"],\n \"user_prompt\": \"job ad pages\",\n \"max_crawl_depth\": 2,\n \"limit\": 10,\n \"geo_location\": \"Germany\",\n \"render_javascript\": False,\n \"include_sitemap\": True,\n \"max_credits\": None,\n \"allow_subdomains\": False,\n \"allow_external_domains\": False,\n}\nresult = ai_map.map(**payload)\nprint(result.data)\n```\n\n资料来源：[readme.md](https://github.com/oxylabs/oxylabs-ai-studio-py/blob/main/readme.md)\n\n## 工作流程\n\n```mermaid\ngraph TD\n A[输入 URL 和配置] --> B[初始化爬取任务]\n B --> C{include_sitemap 配置}\n C -->|是| D[解析并加载 sitemap]\n C -->|否| E[跳过 sitemap]\n D --> F[生成初始 URL 队列]\n E --> F\n F --> G[按 max_crawl_depth 层级爬取]\n G --> H{search_keywords 过滤}\n H -->|匹配| I[URL 进入结果集]\n H -->|不匹配| J[丢弃]\n I --> K{limit 检查}\n K -->|未达上限| G\n K -->|已达上限| L[返回映射结果]\n J --> G\n```\n\n## 参数说明\n\n### 必需参数\n\n| 参数名 | 类型 | 说明 |\n|--------|------|------|\n| url | str | 起始 URL 或域名，用于开始映射任务 |\n\n### 可选参数\n\n| 参数名 | 类型 | 默认值 | 说明 |\n|--------|------|--------|------|\n| search_keywords | list[str] | None | 用于过滤 URL 路径的关键词列表 |\n| user_prompt | str \\| None | None | 自然语言提示，用于关键词搜索。可与 search_keywords 配合使用或单独使用 |\n| max_crawl_depth | int | 1 | 最大爬取深度，范围 1-5 |\n| limit | int | 25 | 返回的最大 URL 数量 |\n| geo_location | str | None | 代理位置，使用 ISO2 格式或国家标准名称 |\n| render_javascript | bool | False | 是否启用 JavaScript 渲染 |\n| include_sitemap | bool | True | 是否将 sitemap 作为种子来源 |\n| max_credits | int \\| None | None | 使用的最大积分额度 |\n| allow_subdomains | bool | False | 是否允许爬取子域名 |\n| allow_external_domains | bool | False | 是否允许爬取外部域名 |\n\n## 配置详解\n\n### 深度爬取策略\n\n`max_crawl_depth` 参数控制爬取遍历的层级深度。合理的深度设置对结果质量和资源消耗有显著影响：\n\n| 深度值 | 适用场景 | 预期 URL 数量 |\n|--------|----------|---------------|\n| 1 | 浅层页面发现 | 10-50 |\n| 2 | 一般网站结构探索 | 50-200 |\n| 3 | 中型网站完整映射 | 200-1000 |\n| 4-5 | 大型网站深层探索 | 1000+ |\n\n### 关键词过滤机制\n\n`search_keywords` 参数支持多关键词匹配，URL 路径中包含任一关键词的页面将被保留：\n\n```python\npayload = {\n \"url\": \"https://example.com\",\n \"search_keywords\": [\"product\", \"category\", \"search\"],\n # ...\n}\n```\n\n资料来源：[readme.md](https://github.com/oxylabs/oxylabs-ai-studio-py/blob/main/readme.md)\n\n### 域名访问控制\n\n通过 `allow_subdomains` 和 `allow_external_domains` 两个布尔参数，可以精确控制爬取范围：\n\n| allow_subdomains | allow_external_domains | 行为描述 |\n|------------------|------------------------|----------|\n| False | False | 仅爬取主域名，不含子域名和外部链接 |\n| True | False | 允许子域名，但不允许外部域名 |\n| False | True | 允许外部域名，但不允许子域名 |\n| True | True | 无限制，所有域名均可访问 |\n\n### Sitemap 集成\n\n`include_sitemap` 参数默认为 `True`，这意味着模块会自动尝试从 `域名/sitemap.xml` 获取已知的 URL 作为种子。如果网站没有 sitemap 文件或文件不完整，建议同时配置 `search_keywords` 以确保发现更多相关页面。\n\n## 返回结果\n\nAI-Map 的 `map()` 方法返回 `AiMapJob` 对象，包含以下属性：\n\n| 属性 | 类型 | 说明 |\n|------|------|------|\n| run_id | str | 任务唯一标识符 |\n| message | str \\| None | 状态消息或错误信息 |\n| data | dict \\| None | 映射结果数据 |\n\n访问结果数据的方式：\n\n```python\nresult = ai_map.map(**payload)\nprint(result.data)\n```\n\n## 使用场景\n\n### 场景一：职位页面发现\n\n当需要在招聘网站中查找所有职位相关页面时：\n\n```python\npayload = {\n \"url\": \"https://career.oxylabs.io\",\n \"search_keywords\": [\"career\", \"jobs\", \"vacancy\"],\n \"user_prompt\": \"job ad pages\",\n \"max_crawl_depth\": 2,\n \"limit\": 10,\n \"geo_location\": \"Germany\",\n \"render_javascript\": False,\n \"include_sitemap\": True,\n}\n```\n\n资料来源：[readme.md](https://github.com/oxylabs/oxylabs-ai-studio-py/blob/main/readme.md)\n\n### 场景二：电商产品分类映射\n\n对于电商站点，需要发现所有产品分类页面：\n\n```python\npayload = {\n \"url\": \"https://shop.example.com\",\n \"search_keywords\": [\"category\", \"products\", \"collections\"],\n \"user_prompt\": \"product category pages\",\n \"max_crawl_depth\": 3,\n \"limit\": 50,\n \"include_sitemap\": True,\n \"allow_subdomains\": False,\n}\n```\n\n## 与其他模块的协作\n\nAI-Map 通常作为数据采集流程的起始环节：\n\n```mermaid\ngraph LR\n A[AI-Map] --> B[发现目标 URL 列表]\n B --> C[AI-Scraper]\n C --> D[提取页面内容]\n D --> E[AI-Crawler]\n E --> F[深度数据采集]\n```\n\n典型工作流：\n\n1. **使用 AI-Map 发现相关页面** - 通过关键词定位目标 URL\n2. **使用 AI-Scraper 提取结构化数据** - 对单个或少量页面进行精确提取\n3. **使用 AI-Crawler 进行大规模采集** - 对发现的所有相关页面进行批量内容提取\n\n## 错误处理\n\nAI-Map 抛出的主要异常类型：\n\n| 异常类型 | 触发条件 | 处理建议 |\n|----------|----------|----------|\n| ValueError | 必要参数缺失或格式错误 | 检查 payload 配置 |\n| Exception | API 请求失败 | 检查网络连接和 API Key 有效性 |\n| TimeoutError | 任务执行超时 | 增加 timeout 配置或减少 limit |\n\n## 最佳实践\n\n1. **渐进式探索**：从 `max_crawl_depth=1` 开始，确认结果符合预期后再逐步增加深度\n2. **精准关键词**：使用精确的路径关键词可大幅减少无关页面的发现\n3. **积分控制**：通过 `max_credits` 设置消费上限，避免意外超支\n4. **sitemap 优先**：大多数站点 sitemap 包含完整结构，建议保持 `include_sitemap=True`\n5. **地理定位**：根据目标用户群体设置 `geo_location`，获取区域性内容\n\n---\n\n\n\n## Browser Agent 文档\n\n### 相关页面\n\n相关主题：[AI-Scraper 文档](#ai-scraper), [Schema 生成指南](#schema-generation)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [src/oxylabs_ai_studio/apps/browser_agent.py](https://github.com/oxylabs/oxylabs-ai-studio-py/blob/main/src/oxylabs_ai_studio/apps/browser_agent.py)\n- [examples/browser_agent.py](https://github.com/oxylabs/oxylabs-ai-studio-py/blob/main/examples/browser_agent.py)\n- [agentic_code_guide.md](https://github.com/oxylabs/oxylabs-ai-studio-py/blob/main/agentic_code_guide.md)\n- [readme.md](https://github.com/oxylabs/oxylabs-ai-studio-py/blob/main/readme.md)\n \n\n# Browser Agent 文档\n\n## 概述\n\nBrowser Agent 是 Oxylabs AI Studio Python SDK 中的一个核心模块，提供基于 AI 的浏览器自动化能力。该模块能够控制浏览器执行点击、滚动、导航等操作，并根据自然语言提示完成复杂的数据提取任务。\n\nBrowser Agent 的主要特点包括：\n\n- 支持同步和异步两种调用方式\n- 内置自动模式识别功能，可根据输出格式自动生成 JSON Schema\n- 支持多种输出格式（JSON、Markdown、HTML、Screenshot、CSV、Toon）\n- 提供地理位置模拟能力，可设置代理位置\n- 支持 JavaScript 渲染\n- 可自定义 User-Agent 请求头\n\n资料来源：[readme.md](https://github.com/oxylabs/oxylabs-ai-studio-py/blob/main/readme.md)\n\n## 架构设计\n\n### 组件关系图\n\n```mermaid\ngraph TD\n A[BrowserAgent] --> B[API 调用层]\n B --> C[轮询机制]\n C --> D{状态检查}\n D -->|processing| E[等待继续轮询]\n D -->|completed| F[返回 BrowserAgentJob]\n D -->|failed| G[返回失败状态]\n E --> D\n B --> H[Async Client]\n H --> I[异步轮询机制]\n I --> J{异步状态检查}\n J -->|processing| K[异步等待]\n J -->|completed| L[返回 BrowserAgentJob]\n J -->|failed| M[返回失败状态]\n```\n\n### 核心数据模型\n\nBrowser Agent 使用 Pydantic 模型定义返回数据结构：\n\n| 模型名称 | 字段 | 类型 | 说明 |\n|---------|------|------|------|\n| `DataModel` | type | `Literal[\"json\", \"markdown\", \"html\", \"screenshot\", \"csv\"]` | 输出内容类型 |\n| `DataModel` | content | `dict[str, Any] \\| str \\| None` | 实际返回的数据内容 |\n| `BrowserAgentJob` | run_id | `str` | 任务唯一标识符 |\n| `BrowserAgentJob` | message | `str \\| None` | 错误信息或状态消息 |\n| `BrowserAgentJob` | data | `DataModel \\| None` | 结构化的任务数据 |\n\n资料来源：[agentic_code_guide.md](https://github.com/oxylabs/oxylabs-ai-studio-py/blob/main/agentic_code_guide.md)\n\n## 安装与初始化\n\n### 安装 SDK\n\n```bash\npip install oxylabs-ai-studio\n```\n\n### 初始化 Browser Agent\n\n```python\nfrom oxylabs_ai_studio.apps.browser_agent import BrowserAgent\n\nbrowser_agent = BrowserAgent(api_key=\"\")\n```\n\n## API 参数说明\n\n### run 方法参数\n\n| 参数名 | 类型 | 必填 | 默认值 | 说明 |\n|--------|------|------|--------|------|\n| url | str | 是 | - | 目标网页 URL |\n| user_prompt | str | 是 | - | 执行浏览器操作的自然语言提示 |\n| output_format | Literal[\"json\", \"markdown\", \"html\", \"screenshot\", \"csv\", \"toon\"] | 否 | \"markdown\" | 输出格式 |\n| schema | dict \\| None | 否 | None | JSON Schema（当 output_format 为 \"json\" 时必填） |\n| geo_location | str | 否 | None | 代理位置（ISO2 格式或国家名称） |\n| render_javascript | bool \\| str | 否 | False | JavaScript 渲染设置，可设为 \"auto\" 自动检测 |\n| user_agent | str | 否 | None | 自定义 User-Agent 请求头 |\n\n资料来源：[readme.md](https://github.com/oxylabs/oxylabs-ai-studio-py/blob/main/readme.md)\n\n### generate_schema 方法参数\n\n| 参数名 | 类型 | 必填 | 说明 |\n|--------|------|------|------|\n| prompt | str | 是 | 用于生成 JSON Schema 的自然语言描述 |\n\n## 使用示例\n\n### 同步调用示例\n\n```python\nfrom oxylabs_ai_studio.apps.browser_agent import BrowserAgent\n\nbrowser_agent = BrowserAgent(api_key=\"\")\n\n# 生成 Schema\nschema = browser_agent.generate_schema(\n prompt=\"game name, platform, review stars and price\"\n)\nprint(\"schema: \", schema)\n\n# 执行浏览器任务\nprompt = \"Find if there is game 'super mario odyssey' in the store. If there is, find the price. Use search bar to find the game.\"\nurl = \"https://sandbox.oxylabs.io/\"\nresult = browser_agent.run(\n url=url,\n user_prompt=prompt,\n output_format=\"json\",\n schema=schema,\n geo_location=\"Spain\",\n)\nprint(result.data)\n```\n\n资料来源：[examples/browser_agent.py](https://github.com/oxylabs/oxylabs-ai-studio-py/blob/main/examples/browser_agent.py)\n\n### 异步调用示例\n\n```python\nimport asyncio\nfrom oxylabs_ai_studio.apps.browser_agent import BrowserAgent\n\nbrowser_agent = BrowserAgent(api_key=\"\")\n\nasync def main():\n prompt = \"Find if there is game 'super mario odyssey' in the store.\"\n url = \"https://sandbox.oxylabs.io/\"\n result = await browser_agent.run_async(\n url=url,\n user_prompt=prompt,\n output_format=\"json\",\n schema={\"type\": \"object\", \"properties\": {\"page_url\": {\"type\": \"string\"}}, \"required\": []},\n )\n print(result.data)\n\nif __name__ == \"__main__\":\n asyncio.run(main())\n```\n\n资料来源：[agentic_code_guide.md](https://github.com/oxylabs/oxylabs-ai-studio-py/blob/main/agentic_code_guide.md)\n\n### 异步 Schema 生成\n\n```python\nimport asyncio\nfrom oxylabs_ai_studio.apps.browser_agent import BrowserAgent\n\nbrowser_agent = BrowserAgent(api_key=\"\")\n\nasync def main():\n schema = await browser_agent.generate_schema_async(\n prompt=\"game name, platform, review stars and price\"\n )\n print(\"Generated schema:\", schema)\n\nif __name__ == \"__main__\":\n asyncio.run(main())\n```\n\n## 执行流程\n\n```mermaid\nsequenceDiagram\n participant Client\n participant BrowserAgent\n participant API\n \n Client->>BrowserAgent: run(url, user_prompt, output_format, schema)\n BrowserAgent->>API: POST /browser-agent/run\n API-->>BrowserAgent: {run_id, status}\n BrowserAgent->>API: GET /browser-agent/run/data?run_id={run_id}\n API-->>BrowserAgent: status: processing\n Note over BrowserAgent: 轮询等待\n BrowserAgent->>API: GET /browser-agent/run/data?run_id={run_id}\n API-->>BrowserAgent: status: completed\n BrowserAgent-->>Client: BrowserAgentJob(data)\n```\n\n## 错误处理与超时\n\n### 超时机制\n\nBrowser Agent 内置超时检测，当请求超时时抛出 `TimeoutError`：\n\n```python\ntry:\n result = browser_agent.run(\n url=url,\n user_prompt=prompt,\n output_format=\"json\",\n schema=schema,\n )\nexcept TimeoutError as e:\n print(f\"请求超时: {e}\")\n```\n\n### 用户取消\n\n用户可通过键盘中断（KeyboardInterrupt）取消正在执行的爬取任务：\n\n```python\ntry:\n result = browser_agent.run(\n url=url,\n user_prompt=prompt,\n output_format=\"json\",\n schema=schema,\n )\nexcept KeyboardInterrupt:\n logger.info(\"[Cancelled] Browser agent was cancelled by user.\")\n```\n\n资料来源：[src/oxylabs_ai_studio/apps/browser_agent.py](https://github.com/oxylabs/oxylabs-ai-studio-py/blob/main/src/oxylabs_ai_studio/apps/browser_agent.py)\n\n## 返回值结构\n\n### 成功响应\n\n```python\nBrowserAgentJob(\n run_id=\"xxx-xxx-xxx\",\n message=None,\n data=DataModel(\n type=\"json\",\n content={\"game_name\": \"Super Mario Odyssey\", \"price\": \"$59.99\"}\n )\n)\n```\n\n### 失败响应\n\n```python\nBrowserAgentJob(\n run_id=\"xxx-xxx-xxx\",\n message=\"error_code\",\n data=None\n)\n```\n\n## 与其他模块的对比\n\n| 功能 | Browser Agent | AI Scraper | AI Crawler |\n|------|---------------|------------|------------|\n| 交互式操作 | ✅ 支持点击、滚动、导航 | ❌ 仅静态页面提取 | ❌ 仅静态页面爬取 |\n| 输出格式 | JSON, Markdown, HTML, Screenshot, CSV, Toon | JSON, Markdown, CSV, Screenshot, Toon | JSON, Markdown, CSV, Toon |\n| Schema 生成 | ✅ 内置 generate_schema | ✅ 内置 generate_schema | ✅ 内置 generate_schema |\n| 地理位置 | ✅ 支持 | ✅ 支持 | ✅ 支持 |\n| JavaScript 渲染 | ✅ 支持 | ✅ 支持 | ✅ 支持 |\n\n## 最佳实践\n\n1. **合理设置 user_prompt**：提示词应描述要执行的操作，而非单纯说明要提取的内容\n2. **使用 Schema 限制输出**：当需要结构化数据时，预先定义 JSON Schema\n3. **处理异步操作**：对于大量任务，优先使用 `run_async` 方法提高效率\n4. **设置合理的超时时间**：根据目标网站响应时间调整超时配置\n5. **地理位置选择**：根据目标网站的地区限制选择合适的 geo_location 参数\n\n## 限制与注意事项\n\n- Python 版本要求：3.10 及以上\n- 需要有效的 API Key\n- 部分功能可能产生额外的 API 调用费用\n- 地理位置参数需使用支持的 ISO2 格式或国家规范名称\n\n---\n\n\n\n## API 客户端架构\n\n### 相关页面\n\n相关主题：[数据模型](#data-models), [快速入门](#quick-start)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [src/oxylabs_ai_studio/client.py](https://github.com/oxylabs/oxylabs-ai-studio-py/blob/main/src/oxylabs_ai_studio/client.py)\n- [src/oxylabs_ai_studio/logger.py](https://github.com/oxylabs/oxylabs-ai-studio-py/blob/main/src/oxylabs_ai_studio/logger.py)\n- [src/oxylabs_ai_studio/settings.py](https://github.com/oxylabs/oxylabs-ai-studio-py/blob/main/src/oxylabs_ai_studio/settings.py)\n- [src/oxylabs_ai_studio/utils.py](https://github.com/oxylabs/oxylabs-ai-studio-py/blob/main/src/oxylabs_ai_studio/utils.py)\n- [src/oxylabs_ai_studio/apps/browser_agent.py](https://github.com/oxylabs/oxylabs-ai-studio-py/blob/main/src/oxylabs_ai_studio/apps/browser_agent.py)\n \n\n# API 客户端架构\n\n## 概述\n\nOxylabs AI Studio Python SDK 的核心架构采用**面向对象继承模式**，所有应用模块均继承自统一的基类 `OxyStudioAIClient`。该架构设计遵循**单一职责原则**，将 HTTP 通信、日志记录、配置管理和业务逻辑分离到不同的模块中，实现了高度的内聚性和低耦合性。\n\n客户端架构支持以下核心功能：\n\n- 同步与异步双接口设计\n- 自动重试与超时处理\n- 结构化数据提取\n- 代理地理位置定位\n- JavaScript 渲染支持\n\n## 架构分层\n\n```mermaid\ngraph TD\n subgraph \"表现层 (Presentation Layer)\"\n A[应用模块: AiCrawler
AiScraper
AiSearch
BrowserAgent
AiMap]\n end\n \n subgraph \"核心客户端层 (Core Client Layer)\"\n B[OxyStudioAIClient]\n end\n \n subgraph \"工具层 (Utility Layer)\"\n C[logger.py]\n D[settings.py]\n E[utils.py]\n end\n \n subgraph \"数据模型层 (Data Model Layer)\"\n F[models.py
SchemaResponse
AiScraperJob
BrowserAgentJob]\n end\n \n subgraph \"外部服务层\"\n G[Oxylabs AI Studio API]\n end\n \n A --> B\n B --> C\n B --> D\n B --> E\n B --> F\n B --> G\n```\n\n## 核心组件详解\n\n### 1. OxyStudioAIClient 基类\n\n`OxyStudioAIClient` 是所有应用模块的父类，位于 `src/oxylabs_ai_studio/client.py`。该类封装了所有与 API 通信的通用逻辑。\n\n#### 核心职责\n\n| 职责 | 说明 |\n|------|------|\n| API 认证 | 管理 API Key 的存储与传递 |\n| HTTP 请求 | 封装 GET/POST 请求方法 |\n| 响应处理 | 统一处理 API 响应格式 |\n| 错误处理 | 异常捕获与日志记录 |\n| 重试机制 | 自动重试失败的请求 |\n\n#### 继承结构\n\n```python\nclass OxyStudioAIClient:\n def __init__(self, api_key: str | None = None):\n \"\"\"初始化客户端实例\"\"\"\n pass\n \n def get_client(self) -> httpx.Client:\n \"\"\"获取 HTTP 客户端实例\"\"\"\n pass\n \n def call_api(self, client, url, method, **kwargs) -> httpx.Response:\n \"\"\"调用 API 的通用方法\"\"\"\n pass\n```\n\n所有应用模块继承此基类：\n\n```python\nclass BrowserAgent(OxyStudioAIClient):\n def __init__(self, api_key: str | None = None):\n super().__init__(api_key=api_key)\n\nclass AiScraper(OxyStudioAIClient):\n # 继承相同模式\n pass\n\nclass AiCrawler(OxyStudioAIClient):\n # 继承相同模式\n pass\n```\n\n资料来源：[src/oxylabs_ai_studio/client.py](https://github.com/oxylabs/oxylabs-ai-studio-py/blob/main/src/oxylabs_ai_studio/client.py)\n\n### 2. 应用模块\n\nSDK 提供五个主要应用模块，每个模块对应特定的数据采集场景：\n\n| 模块 | 功能 | 输出格式 |\n|------|------|----------|\n| AiCrawler | 网站爬取与深度遍历 | json, markdown, csv, toon |\n| AiScraper | 单页面结构化提取 | json, markdown, csv, screenshot, toon |\n| AiSearch | 搜索引擎结果抓取 | json (含 content 选项) |\n| BrowserAgent | 浏览器自动化操作 | json, markdown |\n| AiMap | 站点地图发现 | - |\n\n#### 同步与异步接口模式\n\n每个应用模块同时提供同步 (`run`/`scrape`/`search`) 和异步 (`run_async`/`scrape_async`/`search_async`) 接口：\n\n```python\n# 同步接口\nresult = scraper.scrape(url=url, output_format=\"markdown\")\n\n# 异步接口\nresult = await scraper.scrape_async(url=url, output_format=\"markdown\")\n```\n\n### 3. 日志系统\n\n日志模块位于 `src/oxylabs_ai_studio/logger.py`，采用 Python 标准库 `logging` 实现。\n\n#### 日志级别配置\n\n```python\nlogger = get_logger(__name__)\n\nlogger.info(\"正在生成 schema\")\nlogger.error(f\"API 调用失败: {response.text}\")\n```\n\n#### 日志输出目标\n\n- 控制台 (Console)\n- 可配置的日志文件\n\n### 4. 配置管理\n\n`src/oxylabs_ai_studio/settings.py` 负责管理 SDK 全局配置：\n\n| 配置项 | 类型 | 说明 |\n|--------|------|------|\n| API_BASE_URL | str | API 基础 URL |\n| TIMEOUT | int | 请求超时时间（秒） |\n| MAX_RETRIES | int | 最大重试次数 |\n| POLL_INTERVAL | int | 轮询间隔（秒） |\n\n### 5. 工具函数\n\n`src/oxylabs_ai_studio/utils.py` 提供通用辅助函数：\n\n- 数据验证\n- 响应格式化\n- 错误码映射\n\n## 请求流程\n\n### 标准请求流程\n\n```mermaid\nsequenceDiagram\n participant User as 用户代码\n participant App as 应用模块\n participant Client as OxyStudioAIClient\n participant API as Oxylabs API\n participant Response as 响应数据\n\n User->>App: 调用方法 (scrape/crawl/search)\n App->>App: 参数验证与格式化\n App->>Client: call_api(client, url, method, body)\n Client->>API: HTTP POST/GET 请求\n API-->>Client: 202 (处理中) 或 200 (完成)\n \n alt 长任务 (状态码 202)\n Client->>Client: 轮询直到完成\n loop 轮询\n Client->>API: GET /status\n API-->>Client: status: processing\n end\n end\n \n Client-->>App: 返回响应数据\n App-->>User: 返回 Job 对象\n```\n\n### 长任务轮询机制\n\n对于需要较长时间处理的任务（如爬取大量页面），SDK 采用轮询机制：\n\n```python\nPOLL_INTERVAL_SECONDS = 5\nPOLL_MAX_ATTEMPTS = 120 # 默认 10 分钟超时\n```\n\n状态转换：\n\n```mermaid\nstateDiagram-v2\n [*] --> Submitted: POST /run\n Submitted --> Processing: 202 响应\n Processing --> Processing: 继续轮询\n Processing --> Completed: 200 + status=completed\n Processing --> Failed: status=failed\n Completed --> [*]\n Failed --> [*]\n```\n\n资料来源：[src/oxylabs_ai_studio/apps/browser_agent.py:6-7](https://github.com/oxylabs/oxylabs-ai-studio-py/blob/main/src/oxylabs_ai_studio/apps/browser_agent.py)\n\n## 数据模型\n\n### 通用响应模型\n\n所有应用模块返回统一的 Job 对象结构：\n\n```python\nclass AiScraperJob(BaseModel):\n run_id: str\n message: str | None = None\n data: str | dict | None\n\nclass BrowserAgentJob(BaseModel):\n run_id: str\n message: str | None = None\n data: DataModel | None = None\n\nclass DataModel(BaseModel):\n type: Literal[\"json\", \"markdown\", \"html\", \"screenshot\", \"csv\"]\n content: dict[str, Any] | str | None\n```\n\n### Schema 响应模型\n\n```python\nclass SchemaResponse(BaseModel):\n schema: dict[str, Any]\n user_prompt: str\n```\n\n## 认证机制\n\nAPI 认证采用 **API Key** 方式，通过 HTTP Header 传递：\n\n```python\nheaders = {\n \"Authorization\": f\"Bearer {self.api_key}\",\n \"Content-Type\": \"application/json\"\n}\n```\n\n初始化方式：\n\n```python\n# 方式一：直接传入\nscraper = AiScraper(api_key=\"your-api-key\")\n\n# 方式二：环境变量\n# 设置环境变量 OXyLABS_API_KEY\nscraper = AiScraper() # 自动从环境变量读取\n```\n\n## 错误处理\n\n### 错误类型\n\n| 错误类型 | 触发条件 | 处理方式 |\n|----------|----------|----------|\n| `ValueError` | 参数验证失败 | 检查输入参数 |\n| `httpx.HTTPStatusError` | HTTP 4xx/5xx 错误 | 检查 API Key 和网络 |\n| `TimeoutError` | 请求超时 | 增加超时时间 |\n| `KeyboardInterrupt` | 用户取消操作 | 优雅退出 |\n\n### 参数验证示例\n\n```python\ndef scrape(self, ..., output_format: str, schema: dict | None = None):\n if output_format in [\"json\", \"csv\", \"toon\"] and schema is None:\n raise ValueError(\n \"schema is required when output_format is json, csv or toon.\"\n )\n```\n\n## 高级配置\n\n### 地理位置定位\n\n通过 `geo_location` 参数指定代理位置：\n\n```python\nresult = scraper.scrape(\n url=\"https://example.com\",\n geo_location=\"Germany\", # 或 \"DE\" ISO2 格式\n)\n```\n\n支持的格式：\n- ISO 2-letter 代码：`\"DE\"`, `\"US\"`, `\"IT\"`\n- 国家名称：`\"Germany\"`, `\"United States\"`\n\n### JavaScript 渲染\n\n```python\n# 禁用 JS 渲染 (默认)\nrender_javascript=False\n\n# 启用 JS 渲染\nrender_javascript=True\n\n# 自动检测\nrender_javascript=\"auto\"\n```\n\n### 结构化提取\n\n使用 JSON Schema 定义输出结构：\n\n```python\nschema = {\n \"type\": \"object\",\n \"properties\": {\n \"title\": {\"type\": \"string\"},\n \"price\": {\"type\": \"string\"},\n \"features\": {\n \"type\": \"array\",\n \"items\": {\"type\": \"string\"}\n }\n },\n \"required\": [\"title\", \"price\"]\n}\n```\n\n或使用 Pydantic 模型自动生成 Schema：\n\n```python\nfrom pydantic import BaseModel, Field\n\nclass Product(BaseModel):\n title: str = Field(description=\"产品名称\")\n price: str = Field(description=\"产品价格\")\n\nschema = Product.model_json_schema()\n```\n\n## 使用示例\n\n### 基础用法\n\n```python\nfrom oxylabs_ai_studio.apps.ai_scraper import AiScraper\n\nscraper = AiScraper(api_key=\"\")\nresult = scraper.scrape(\n url=\"https://example.com/products/1\",\n output_format=\"markdown\",\n)\nprint(result.data)\n```\n\n### 异步用法\n\n```python\nimport asyncio\nfrom oxylabs_ai_studio.apps.ai_scraper import AiScraper\n\nscraper = AiScraper(api_key=\"\")\n\nasync def main():\n result = await scraper.scrape_async(\n url=\"https://example.com/products/1\",\n output_format=\"json\",\n schema={\"type\": \"object\", \"properties\": {\"title\": {\"type\": \"string\"}}},\n )\n print(result.data)\n\nasyncio.run(main())\n```\n\n## 最佳实践\n\n1. **API Key 管理**：使用环境变量存储 API Key，避免硬编码\n2. **错误处理**：捕获特定异常类型，进行针对性处理\n3. **重试机制**：实现指数退避策略处理临时性失败\n4. **超时配置**：根据任务复杂度合理设置超时时间\n5. **异步批量处理**：大量请求时使用异步接口提高吞吐量\n\n---\n\n\n\n## 数据模型\n\n### 相关页面\n\n相关主题：[API 客户端架构](#api-client), [Schema 生成指南](#schema-generation)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [src/oxylabs_ai_studio/apps/ai_search.py](https://github.com/oxylabs/oxylabs-ai-studio-py/blob/main/src/oxylabs_ai_studio/apps/ai_search.py)\n- [src/oxylabs_ai_studio/apps/ai_scraper.py](https://github.com/oxylabs/oxylabs-ai-studio-py/blob/main/src/oxylabs_ai_studio/apps/ai_scraper.py)\n- [src/oxylabs_ai_studio/apps/ai_crawler.py](https://github.com/oxylabs/oxylabs-ai-studio-py/blob/main/src/oxylabs_ai_studio/apps/ai_crawler.py)\n- [src/oxylabs_ai_studio/apps/ai_map.py](https://github.com/oxylabs/oxylabs-ai-studio-py/blob/main/src/oxylabs_ai_studio/apps/ai_map.py)\n- [agentic_code_guide.md](https://github.com/oxylabs/oxylabs-ai-studio-py/blob/main/agentic_code_guide.md)\n- [examples/crawl_pydantic_schema.py](https://github.com/oxylabs/oxylabs-ai-studio-py/blob/main/examples/crawl_pydantic_schema.py)\n \n\n# 数据模型\n\n## 概述\n\nOxylabs AI Studio Python SDK 的数据模型是整个SDK架构的核心组成部分，定义了各应用模块返回数据结构的一致性模式。SDK采用Pydantic作为数据验证库，为所有API响应提供类型安全的数据结构。\n\n数据模型系统包含两类核心模型：作业模型（Job Models）和数据模型（Data Models）。作业模型封装了API调用的完整响应信息，包括任务标识符、状态消息和实际数据内容。数据模型则定义了具体输出的格式和结构，支持多种输出类型如JSON、Markdown、HTML、CSV和Screenshot。\n\n## 核心数据模型架构\n\n### 模型继承关系\n\n```mermaid\ngraph TD\n A[BaseModel - Pydantic] --> B[AiSearchJob]\n A --> C[AiScraperJob]\n A --> D[AiCrawlerJob]\n A --> E[AiMapJob]\n A --> F[BrowserAgentJob]\n \n G[DataModel] --> C\n G --> F\n \n H[SchemaResponse] --> I[内部响应模型]\n```\n\n## 作业模型详解\n\n### AiSearchJob 搜索作业模型\n\n`AiSearchJob` 是搜索功能的返回模型，用于封装SERP（搜索引擎结果页面）搜索操作的结果。该模型继承自Pydantic的BaseModel，确保数据类型的安全性。\n\n| 字段名 | 类型 | 描述 |\n|--------|------|------|\n| run_id | str | 任务唯一标识符，用于追踪和查询任务状态 |\n| message | str \\| None | 状态消息或错误代码 |\n| data | Any \\| None | 搜索结果数据内容 |\n\n```python\nclass AiSearchJob(BaseModel):\n run_id: str\n message: str | None = None\n data: Any | None = None\n```\n\n资料来源：[src/oxylabs_ai_studio/apps/ai_search.py:1-100]()\n\n搜索功能支持两种模式：标准搜索和即时搜索。即时搜索在满足`limit <= 10`且`return_content=False`条件时自动启用，直接返回结果而无需轮询状态。\n\n### AiScraperJob 网页抓取作业模型\n\n`AiScraperJob` 是网页抓取功能的核心返回模型，与搜索模型类似但增加了对多种输出格式的支持。\n\n| 字段名 | 类型 | 描述 |\n|--------|------|------|\n| run_id | str | 任务唯一标识符 |\n| message | str \\| None | 错误信息或状态描述 |\n| data | str \\| dict \\| None | 根据output_format返回不同类型的数据 |\n\n```python\nclass AiScraperJob(BaseModel):\n run_id: str\n message: str | None = None\n data: str | dict | None\n```\n\n资料来源：[agentic_code_guide.md](https://github.com/oxylabs/oxylabs-ai-studio-py/blob/main/agentic_code_guide.md)\n\nAiScraperJob的data字段根据output_format参数呈现不同类型：JSON格式返回字典对象，Markdown格式返回字符串，CSV格式返回逗号分隔的字符串，Screenshot格式返回Base64编码的字符串。\n\n### AiCrawlerJob 网站爬取作业模型\n\n`AiCrawlerJob` 用于封装网站爬取功能的结果，支持批量URL的数据提取。该模型返回的data字段为列表类型，每个元素代表一个页面的提取结果。\n\n```python\nclass AiCrawlerJob(BaseModel):\n run_id: str\n message: str | None = None\n data: list[Any] | None = None\n```\n\n资料来源：[src/oxylabs_ai_studio/apps/ai_crawler.py:1-100]()\n\n爬取功能支持自定义Pydantic Schema进行结构化数据提取，可以定义复杂的嵌套数据类型：\n\n```python\nclass ProxyPlan(BaseModel):\n name: str = Field(description=\"The name of the proxy plan\")\n price: str = Field(description=\"The price of the proxy plan\")\n features: list[str] = Field(description=\"The features of the proxy plan\")\n\nclass ProxyPlans(BaseModel):\n proxy_plans: list[ProxyPlan] = Field(description=\"The proxy plans\")\n```\n\n资料来源：[examples/crawl_pydantic_schema.py:1-25]()\n\n### AiMapJob 站点映射作业模型\n\n`AiMapJob` 是站点映射功能的返回模型，用于生成网站结构地图。该模型返回的数据为字典类型，包含URL与关键词的映射关系。\n\n```python\nclass AiMapJob(BaseModel):\n run_id: str\n message: str | None = None\n data: dict | None = None\n```\n\n资料来源：[src/oxylabs_ai_studio/apps/ai_map.py:1-100]()\n\n### BrowserAgentJob 浏览器代理作业模型\n\n`BrowserAgentJob` 是浏览器代理功能的核心模型，包含DataModel嵌套结构用于封装结构化的页面数据。\n\n```python\nclass DataModel(BaseModel):\n type: Literal[\"json\", \"markdown\", \"html\", \"screenshot\", \"csv\"]\n content: dict[str, Any] | str | None\n\nclass BrowserAgentJob(BaseModel):\n run_id: str\n message: str | None = None\n data: DataModel | None = None\n```\n\n资料来源：[agentic_code_guide.md](https://github.com/oxylabs/oxylabs-ai-studio-py/blob/main/agentic_code_guide.md)\n\n## Schema生成与响应模型\n\n### Schema生成机制\n\nSDK提供智能Schema生成功能，允许用户通过自然语言描述期望的数据结构，系统自动生成对应的JSON Schema。\n\n```mermaid\ngraph LR\n A[自然语言提示] --> B[generate_schema方法]\n B --> C[POST /scrape/schema]\n C --> D[API响应]\n D --> E[openapi_schema]\n E --> F[用于scrape/crawl]\n```\n\n```python\ndef generate_schema(self, prompt: str) -> dict[str, Any] | None:\n logger.info(\"Generating schema\")\n body = {\"user_prompt\": prompt}\n response = self.call_api(\n client=self.get_client(), url=\"/scrape/schema\", method=\"POST\", body=body\n )\n if response.status_code != 200:\n raise Exception(f\"Failed to generate schema: {response.text}\")\n json_response: SchemaResponse = response.json()\n return json_response.get(\"openapi_schema\", None)\n```\n\n资料来源：[src/oxylabs_ai_studio/apps/ai_scraper.py:1-100]()\n\n### SchemaResponse 响应模型\n\n```python\nclass SchemaResponse(BaseModel):\n openapi_schema: dict[str, Any] | None\n```\n\nSchema生成功能同样支持异步调用，通过`generate_schema_async`方法实现：\n\n```python\nasync def generate_schema_async(self, prompt: str) -> dict[str, Any] | None:\n logger.info(\"Generating schema (async)\")\n body = {\"user_prompt\": prompt}\n async with self.async_client() as client:\n response = await self.call_api_async(\n client=client, url=\"/crawl/generate-params\", method=\"POST\", body=body\n )\n # ...\n```\n\n资料来源：[src/oxylabs_ai_studio/apps/ai_crawler.py:1-100]()\n\n## 输出格式与数据类型映射\n\n### 支持的输出格式\n\n| 格式 | 描述 | data字段类型 |\n|------|------|--------------|\n| json | 结构化JSON数据 | dict |\n| markdown | Markdown格式文本 | str |\n| html | 原始HTML内容 | str |\n| screenshot | Base64编码图片 | str |\n| csv | 逗号分隔值格式 | str |\n| toon | 特殊格式 | dict |\n\n### 格式选择指南\n\n```mermaid\ngraph TD\n A[需要结构化数据?] --> |是| B[output_format=json]\n A --> |否| C[需要渲染后内容?]\n C --> |是| D[output_format=screenshot]\n C --> |否| E[需要原始HTML?]\n E --> |是| F[output_format=html]\n E --> |否| G[output_format=markdown]\n \n B --> H[需要schema参数]\n G --> I[可选schema]\n```\n\n选择输出格式时需考虑以下因素：\n\n1. **JSON格式**：需要提供schema参数定义数据结构，适合程序化处理\n2. **Markdown格式**：适合内容提取和文本分析，无需schema\n3. **Screenshot格式**：适合需要渲染JavaScript的动态内容\n4. **CSV格式**：适合表格数据导出，需要schema定义列结构\n\n资料来源：[readme.md](https://github.com/oxylabs/oxylabs-ai-studio-py/blob/main/readme.md)\n\n## 状态轮询与响应处理\n\n### 异步任务状态流程\n\n```mermaid\nstateDiagram-v2\n [*] --> 提交任务\n 提交任务 --> processing: 状态检查\n processing --> processing: 轮询中\n processing --> completed: status==\"completed\"\n processing --> failed: status==\"failed\"\n completed --> [*]\n failed --> [*]\n```\n\n所有作业模型都采用轮询机制获取最终结果：\n\n```python\ndef scrape(self, url: str, ...) -> AiScraperJob:\n # 提交抓取任务\n response = self.call_api(...)\n run_id = response.json()[\"run_id\"]\n \n # 轮询状态直到完成\n while True:\n get_response = self.call_api(...)\n resp_body = get_response.json()\n \n if resp_body[\"status\"] == \"completed\":\n return AiScraperJob(\n run_id=run_id,\n message=resp_body.get(\"error_code\", None),\n data=resp_body.get(\"data\", None),\n )\n \n if resp_body[\"status\"] == \"failed\":\n return AiScraperJob(\n run_id=run_id,\n message=resp_body.get(\"error_code\", None),\n data=None,\n )\n \n time.sleep(POLL_INTERVAL_SECONDS)\n```\n\n资料来源：[src/oxylabs_ai_studio/apps/ai_scraper.py:1-100]()\n\n### 响应状态码处理\n\n| HTTP状态码 | 含义 | SDK处理 |\n|------------|------|---------|\n| 200 | 成功 | 解析JSON并构建Job模型 |\n| 202 | 处理中 | 继续轮询等待 |\n| 4xx | 客户端错误 | 抛出异常 |\n| 5xx | 服务器错误 | 轮询重试 |\n\n## 错误处理与数据验证\n\n### 数据验证机制\n\n所有数据模型使用Pydantic进行运行时类型验证：\n\n```python\nfrom pydantic import BaseModel, Field\n\nclass ProxyPlan(BaseModel):\n name: str = Field(description=\"The name of the proxy plan\")\n price: str = Field(description=\"The price of the proxy plan\")\n features: list[str] = Field(description=\"The features of the proxy plan\")\n```\n\n资料来源：[examples/crawl_pydantic_schema.py:1-25]()\n\n### 异常处理策略\n\n| 异常类型 | 触发条件 | 处理方式 |\n|----------|----------|----------|\n| ValueError | 参数验证失败 | 检查输入参数 |\n| TimeoutError | 轮询超时 | 增加max_credits或检查网络 |\n| KeyboardInterrupt | 用户取消 | 优雅退出并记录日志 |\n| Exception | API错误 | 查看message字段获取详情 |\n\n## 最佳实践\n\n### Schema设计建议\n\n1. 使用明确的Field描述帮助AI理解字段含义\n2. 嵌套模型不要超过3层深度\n3. 数组字段使用有意义的复数名词命名\n4. 始终指定required字段列表\n\n### 数据模型使用示例\n\n```python\nfrom oxylabs_ai_studio.apps.ai_crawler import AiCrawler\n\ncrawler = AiCrawler(api_key=\"\")\n\n# 使用Pydantic模型定义Schema\nschema = ProxyPlans.model_json_schema()\n\nresult = crawler.crawl(\n url=\"https://oxylabs.io\",\n user_prompt=\"Find all pages with proxy products pricing\",\n output_format=\"json\",\n schema=schema,\n)\n\n# 安全访问结果\nfor item in result.data:\n print(item, \"\\n\")\n```\n\n资料来源：[examples/crawl_pydantic_schema.py:1-30]()\n\n## 相关文档\n\n- [AI-Scraper使用指南](agentic_code_guide.md)\n- [示例代码集合](examples/)\n- [API参考文档](readme.md)\n\n---\n\n\n\n## Schema 生成指南\n\n### 相关页面\n\n相关主题：[AI-Scraper 文档](#ai-scraper), [Browser Agent 文档](#browser-agent), [数据模型](#data-models)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [src/oxylabs_ai_studio/apps/ai_scraper.py](https://github.com/oxylabs/oxylabs-ai-studio-py/blob/main/src/oxylabs_ai_studio/apps/ai_scraper.py)\n- [src/oxylabs_ai_studio/apps/browser_agent.py](https://github.com/oxylabs/oxylabs-ai-studio-py/blob/main/src/oxylabs_ai_studio/apps/browser_agent.py)\n- [src/oxylabs_ai_studio/apps/ai_crawler.py](https://github.com/oxylabs/oxylabs-ai-studio-py/blob/main/src/oxylabs_ai_studio/apps/ai_crawler.py)\n- [examples/scrape_generated_schema.py](https://github.com/oxylabs/oxylabs-ai-studio-py/blob/main/examples/scrape_generated_schema.py)\n- [examples/crawl_generated_schema.py](https://github.com/oxylabs/oxylabs-ai-studio-py/blob/main/examples/crawl_generated_schema.py)\n- [examples/browser_agent.py](https://github.com/oxylabs/oxylabs-ai-studio-py/blob/main/examples/browser_agent.py)\n \n\n# Schema 生成指南\n\n## 概述\n\nSchema 生成功能是 oxylabs AI Studio SDK 中的核心特性之一，它允许用户通过自然语言描述自动生成符合 OpenAPI 规范的 JSON Schema，从而实现结构化数据提取。该功能简化了传统手动编写复杂 Schema 的流程，使开发者能够快速定义期望提取的数据结构。\n\nSchema 生成功能在以下三个主要应用模块中可用：\n\n- **AiScraper** - 单页面数据抓取\n- **AiCrawler** - 整站爬取\n- **BrowserAgent** - 浏览器代理操作\n\n## 工作原理\n\nSchema 生成采用自然语言处理技术，将用户的描述性提示转换为标准化的 JSON Schema。生成的 Schema 遵循 OpenAPI 规范，可直接用于指定输出格式为 `json`、`csv` 或 `toon` 时的结构化数据提取。\n\n```mermaid\ngraph LR\n A[自然语言提示] --> B[Schema 生成 API]\n B --> C[JSON Schema]\n C --> D[结构化数据提取]\n \n style A fill:#e1f5fe\n style B fill:#b3e5fc\n style C fill:#81d4fa\n style D fill:#4fc3f7\n```\n\n## 使用方法\n\n### AiScraper 中的 Schema 生成\n\nAiScraper 模块提供了 `generate_schema()` 方法，用于为单页面抓取生成 Schema。\n\n**同步调用示例：**\n\n```python\nfrom oxylabs_ai_studio.apps.ai_scraper import AiScraper\n\nscraper = AiScraper(api_key=\"\")\n\n# 生成 Schema\nschema = scraper.generate_schema(\n prompt=\"want to parse developer, platform, type, price game title, genre (array) and description\"\n)\nprint(f\"Generated schema: {schema}\")\n\n# 使用生成的 Schema 进行抓取\nurl = \"https://sandbox.oxylabs.io/products/3\"\nresult = scraper.scrape(\n url=url,\n output_format=\"json\",\n schema=schema,\n render_javascript=False,\n)\nprint(result)\n```\n\n**参数说明：**\n\n| 参数 | 类型 | 必填 | 说明 |\n|------|------|------|------|\n| prompt | str | 是 | 自然语言描述，指定需要提取的字段及其类型 |\n\n**生成的 Schema 示例：**\n\n```json\n{\n \"type\": \"object\",\n \"properties\": {\n \"developer\": {\"type\": \"string\"},\n \"platform\": {\"type\": \"string\"},\n \"type\": {\"type\": \"string\"},\n \"price\": {\"type\": \"string\"},\n \"game_title\": {\"type\": \"string\"},\n \"genre\": {\"type\": \"array\", \"items\": {\"type\": \"string\"}},\n \"description\": {\"type\": \"string\"}\n },\n \"required\": []\n}\n```\n\n资料来源：[examples/scrape_generated_schema.py](https://github.com/oxylabs/oxylabs-ai-studio-py/blob/main/examples/scrape_generated_schema.py)\n\n### BrowserAgent 中的 Schema 生成\n\nBrowserAgent 模块同样支持 Schema 生成，适用于需要浏览器交互的场景。\n\n**使用示例：**\n\n```python\nfrom oxylabs_ai_studio.apps.browser_agent import BrowserAgent\n\nbrowser_agent = BrowserAgent(api_key=\"\")\n\n# 生成 Schema\nschema = browser_agent.generate_schema(\n prompt=\"game name, platform, review stars and price\"\n)\nprint(\"schema: \", schema)\n\n# 使用生成的 Schema 执行浏览器操作\nprompt = \"Find if there is game 'super mario odyssey' in the store. If there is, find the price. Use search bar to find the game.\"\nurl = \"https://sandbox.oxylabs.io/\"\nresult = browser_agent.run(\n url=url,\n user_prompt=prompt,\n output_format=\"json\",\n schema=schema,\n)\nprint(result.data)\n```\n\n**参数说明：**\n\n| 参数 | 类型 | 必填 | 说明 |\n|------|------|------|------|\n| prompt | str | 是 | 自然语言描述，指定需要提取的字段 |\n\n资料来源：[examples/browser_agent.py](https://github.com/oxylabs/oxylabs-ai-studio-py/blob/main/examples/browser_agent.py)\n\n### AiCrawler 中的 Schema 生成\n\nAiCrawler 模块支持为整站爬取任务生成 Schema。\n\n**使用示例：**\n\n```python\nfrom oxylabs_ai_studio.apps.ai_crawler import AiCrawler\n\ncrawler = AiCrawler(api_key=\"\")\n\n# 生成 Schema\nschema = crawler.generate_schema(\n prompt=\"proxy plans which have name, price, and features\",\n)\nprint(\"schema: \", schema)\n\n# 使用生成的 Schema 进行爬取\nurl = \"https://oxylabs.io\"\nresult = crawler.crawl(\n url=url,\n user_prompt=\"Find all pages with proxy products pricing\",\n output_format=\"json\",\n schema=schema,\n render_javascript=False,\n)\nprint(\"Results:\")\nfor item in result.data:\n print(item, \"\\n\")\n```\n\n资料来源：[examples/crawl_generated_schema.py](https://github.com/oxylabs/oxylabs-ai-studio-py/blob/main/examples/crawl_generated_schema.py)\n\n## 配合 Pydantic 模型使用\n\n生成的 Schema 可以与 Pydantic 模型无缝配合使用，实现类型安全的数据验证。\n\n**示例：**\n\n```python\nfrom pydantic import BaseModel, Field\nfrom oxylabs_ai_studio.apps.ai_crawler import AiCrawler\n\ncrawler = AiCrawler(api_key=\"\")\n\nclass ProxyPlan(BaseModel):\n name: str = Field(description=\"The name of the proxy plan\")\n price: str = Field(description=\"The price of the proxy plan\")\n features: list[str] = Field(description=\"The features of the proxy plan\")\n\nclass ProxyPlans(BaseModel):\n proxy_plans: list[ProxyPlan] = Field(description=\"The proxy plans\")\n\nurl = \"https://oxylabs.io/\"\nresult = crawler.crawl(\n url=url,\n user_prompt=\"Find all pages with proxy products pricing\",\n output_format=\"json\",\n schema=ProxyPlans.model_json_schema(),\n render_javascript=False,\n)\n```\n\n资料来源：[examples/crawl_pydantic_schema.py](https://github.com/oxylabs/oxylabs-ai-studio-py/blob/main/examples/crawl_pydantic_schema.py)\n\n## 输出格式与 Schema 的关系\n\nSchema 生成功能与输出格式紧密相关。不同的输出格式对 Schema 有不同的要求：\n\n| 输出格式 | Schema 要求 | 返回数据类型 |\n|---------|------------|-------------|\n| json | 必须提供 | dict |\n| markdown | 可选 | str |\n| csv | 必须提供 | str |\n| toon | 必须提供 | str |\n| html | 可选 | str |\n| screenshot | 可选 | str |\n\n当输出格式为 `json`、`csv` 或 `toon` 时，必须提供有效的 JSON Schema。Schema 生成功能确保用户能够快速获得符合规范的 Schema 定义。\n\n资料来源：[agentic_code_guide.md](https://github.com/oxylabs/oxylabs-ai-studio-py/blob/main/agentic_code_guide.md)\n\n## 最佳实践\n\n### 1. 字段描述清晰化\n\n在编写 prompt 时，应明确指定每个字段的名称和数据类型：\n\n```python\n# 推荐：明确指定字段\nschema = scraper.generate_schema(\n prompt=\"extract product name (string), price (number), tags (array of strings), and description (string)\"\n)\n\n# 不推荐：描述模糊\nschema = scraper.generate_schema(\n prompt=\"extract product info\"\n)\n```\n\n### 2. 数组字段明确声明\n\n当需要提取数组类型数据时，应在 prompt 中明确说明：\n\n```python\nschema = scraper.generate_schema(\n prompt=\"game title, genre (array) and description\"\n)\n```\n\n### 3. 嵌套对象结构\n\n对于复杂的嵌套数据结构，可以详细描述层级关系：\n\n```python\nschema = crawler.generate_schema(\n prompt=\"proxy plans which have name, price, and features\",\n)\n```\n\n## 实现机制\n\nSchema 生成通过调用后端 API `/crawl/generate-params` 或类似的端点实现：\n\n```python\ndef generate_schema(self, prompt: str) -> dict[str, Any] | None:\n logger.info(\"Generating schema\")\n body = {\"user_prompt\": prompt}\n response = self.call_api(\n client=self.get_client(),\n url=\"/crawl/generate-params\",\n method=\"POST\",\n body=body,\n )\n if response.status_code != 200:\n raise Exception(f\"Failed to generate schema: {response.text}\")\n json_response: SchemaResponse = ...\n```\n\n资料来源：[src/oxylabs_ai_studio/apps/ai_crawler.py](https://github.com/oxylabs/oxylabs-ai-studio-py/blob/main/src/oxylabs_ai_studio/apps/ai_crawler.py)\n\n## 错误处理\n\nSchema 生成过程中可能遇到的错误及处理方式：\n\n| 错误类型 | 可能原因 | 解决方案 |\n|---------|---------|---------|\n| 请求失败 | API 密钥无效或网络问题 | 检查 API 密钥配置和网络连接 |\n| 超时错误 | 后端响应时间过长 | 稍后重试或减少 prompt 复杂度 |\n| 无效 Schema | 生成的 Schema 不符合规范 | 手动调整生成的 Schema 或简化 prompt |\n\n## 总结\n\nSchema 生成功能是 oxylabs AI Studio SDK 的一项强大特性，它通过自然语言处理技术自动将用户的数据提取需求转换为标准化的 JSON Schema。该功能显著降低了结构化数据提取的门槛，使开发者无需深入了解 JSON Schema 规范即可实现复杂的数据提取任务。\n\n通过配合使用 `generate_schema()` 方法和 SDK 的抓取/爬取功能，用户可以快速构建端到端的数据提取工作流，实现从网页内容到结构化数据的自动化转换。\n\n---\n\n---\n\n## Doramagic 踩坑日志\n\n项目：oxylabs/oxylabs-ai-studio-py\n\n摘要：发现 9 个潜在踩坑项，其中 0 个为 high/blocking；最高优先级：身份坑 - 仓库名和安装名不一致。\n\n## 1. 身份坑 · 仓库名和安装名不一致\n\n- 严重度：medium\n- 证据强度：runtime_trace\n- 发现：仓库名 `oxylabs-ai-studio-py` 与安装入口 `oxylabs-ai-studio` 不完全一致。\n- 对用户的影响：用户照着仓库名搜索包或照着包名找仓库时容易走错入口。\n- 建议检查：在 npm/PyPI/GitHub 上确认包名映射和官方 README 说明。\n- 复现命令：`pip install oxylabs-ai-studio`\n- 防护动作：页面必须同时展示 repo 名和真实安装入口，避免用户搜索错包。\n- 证据：identity.distribution | github_repo:1003630893 | https://github.com/oxylabs/oxylabs-ai-studio-py | repo=oxylabs-ai-studio-py; install=oxylabs-ai-studio\n\n## 2. 能力坑 · 能力判断依赖假设\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：README/documentation is current enough for a first validation pass.\n- 对用户的影响：假设不成立时，用户拿不到承诺的能力。\n- 建议检查：将假设转成下游验证清单。\n- 防护动作：假设必须转成验证项；没有验证结果前不能写成事实。\n- 证据：capability.assumptions | github_repo:1003630893 | https://github.com/oxylabs/oxylabs-ai-studio-py | README/documentation is current enough for a first validation pass.\n\n## 3. 维护坑 · 来源证据：v.0.2.19\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个维护/版本相关的待验证问题：v.0.2.19\n- 对用户的影响：可能影响升级、迁移或版本选择。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_96a2e22cbea94aac8c2788f763ce7c04 | https://github.com/oxylabs/oxylabs-ai-studio-py/releases/tag/v0.2.19 | 来源类型 github_release 暴露的待验证使用条件。\n\n## 4. 维护坑 · 维护活跃度未知\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：未记录 last_activity_observed。\n- 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。\n- 建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。\n- 防护动作：维护活跃度未知时，推荐强度不能标为高信任。\n- 证据：evidence.maintainer_signals | github_repo:1003630893 | https://github.com/oxylabs/oxylabs-ai-studio-py | last_activity_observed missing\n\n## 5. 安全/权限坑 · 下游验证发现风险项\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：下游已经要求复核，不能在页面中弱化。\n- 建议检查：进入安全/权限治理复核队列。\n- 防护动作：下游风险存在时必须保持 review/recommendation 降级。\n- 证据：downstream_validation.risk_items | github_repo:1003630893 | https://github.com/oxylabs/oxylabs-ai-studio-py | no_demo; severity=medium\n\n## 6. 安全/权限坑 · 存在安全注意事项\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：No sandbox install has been executed yet; downstream must verify before user use.\n- 对用户的影响：用户安装前需要知道权限边界和敏感操作。\n- 建议检查：转成明确权限清单和安全审查提示。\n- 防护动作：安全注意事项必须面向用户前置展示。\n- 证据：risks.safety_notes | github_repo:1003630893 | https://github.com/oxylabs/oxylabs-ai-studio-py | No sandbox install has been executed yet; downstream must verify before user use.\n\n## 7. 安全/权限坑 · 存在评分风险\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：风险会影响是否适合普通用户安装。\n- 建议检查：把风险写入边界卡，并确认是否需要人工复核。\n- 防护动作：评分风险必须进入边界卡，不能只作为内部分数。\n- 证据：risks.scoring_risks | github_repo:1003630893 | https://github.com/oxylabs/oxylabs-ai-studio-py | no_demo; severity=medium\n\n## 8. 维护坑 · issue/PR 响应质量未知\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：issue_or_pr_quality=unknown。\n- 对用户的影响：用户无法判断遇到问题后是否有人维护。\n- 建议检查：抽样最近 issue/PR，判断是否长期无人处理。\n- 防护动作：issue/PR 响应未知时，必须提示维护风险。\n- 证据：evidence.maintainer_signals | github_repo:1003630893 | https://github.com/oxylabs/oxylabs-ai-studio-py | issue_or_pr_quality=unknown\n\n## 9. 维护坑 · 发布节奏不明确\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：release_recency=unknown。\n- 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。\n- 建议检查：确认最近 release/tag 和 README 安装命令是否一致。\n- 防护动作：发布节奏未知或过期时，安装说明必须标注可能漂移。\n- 证据：evidence.maintainer_signals | github_repo:1003630893 | https://github.com/oxylabs/oxylabs-ai-studio-py | release_recency=unknown\n\n\n",
"markdown_key": "oxylabs-ai-studio-py",
"pages": "draft",
"source_refs": [
{
"evidence_id": "github_repo:1003630893",
"kind": "repo",
"supports_claim_ids": [
"claim_identity",
"claim_distribution",
"claim_capability"
],
"url": "https://github.com/oxylabs/oxylabs-ai-studio-py"
},
{
"evidence_id": "art_55e0da118ad642838591ad36a30fe56c",
"kind": "docs",
"supports_claim_ids": [
"claim_identity",
"claim_distribution",
"claim_capability"
],
"url": "https://github.com/oxylabs/oxylabs-ai-studio-py#readme"
}
],
"summary": "DeepWiki/Human Wiki 完整输出，末尾追加 Discovery Agent 踩坑日志。",
"title": "oxylabs-ai-studio-py 说明书",
"toc": [
"https://github.com/oxylabs/oxylabs-ai-studio-py 项目说明书",
"目录",
"项目介绍",
"项目概述",
"系统架构",
"安装与配置",
"应用模块详解",
"Schema 生成功能",
"Doramagic 踩坑日志"
]
}
},
"quality_gate": {
"blocking_gaps": [],
"category_confidence": "medium",
"compile_status": "ready_for_review",
"five_assets_present": true,
"install_sandbox_verified": true,
"missing_evidence": [],
"next_action": "publish to Doramagic.ai project surfaces",
"prompt_preview_boundary_ok": true,
"publish_status": "publishable",
"quick_start_verified": true,
"repo_clone_verified": false,
"repo_commit": null,
"repo_inspection_error": null,
"repo_inspection_files": [],
"repo_inspection_verified": false,
"review_reasons": [
"community_discussion_evidence_below_public_threshold"
],
"tag_count_ok": true,
"unsupported_claims": []
},
"schema_version": "0.1",
"user_assets": {
"ai_context_pack": {
"asset_id": "ai_context_pack",
"filename": "AI_CONTEXT_PACK.md",
"markdown": "# oxylabs-ai-studio-py - Doramagic AI Context Pack\n\n> 定位：安装前体验与判断资产。它帮助宿主 AI 有一个好的开始，但不代表已经安装、执行或验证目标项目。\n\n## 充分原则\n\n- **充分原则，不是压缩原则**：AI Context Pack 应该充分到让宿主 AI 在开工前理解项目价值、能力边界、使用入口、风险和证据来源；它可以分层组织，但不以最短摘要为目标。\n- **压缩策略**：只压缩噪声和重复内容，不压缩会影响判断和开工质量的上下文。\n\n## 给宿主 AI 的使用方式\n\n你正在读取 Doramagic 为 oxylabs-ai-studio-py 编译的 AI Context Pack。请把它当作开工前上下文：帮助用户理解适合谁、能做什么、如何开始、哪些必须安装后验证、风险在哪里。不要声称你已经安装、运行或执行了目标项目。\n\n## Claim 消费规则\n\n- **事实来源**：Repo Evidence + Claim/Evidence Graph；Human Wiki 只提供显著性、术语和叙事结构。\n- **事实最低状态**：`supported`\n- `supported`：可以作为项目事实使用，但回答中必须引用 claim_id 和证据路径。\n- `weak`：只能作为低置信度线索，必须要求用户继续核实。\n- `inferred`：只能用于风险提示或待确认问题，不能包装成项目事实。\n- `unverified`：不得作为事实使用，应明确说证据不足。\n- `contradicted`：必须展示冲突来源，不得替用户强行选择一个版本。\n\n## 它最适合谁\n\n- **想在安装前理解开源项目价值和边界的用户**：当前证据主要来自项目文档。 Claim：`clm_0002` unverified 0.25\n\n## 它能做什么\n\n- **命令行启动或安装流程**（需要安装后验证）：项目文档中存在可执行命令，真实使用需要在本地或宿主环境中运行这些命令。 证据：`readme.md` Claim：`clm_0001` supported 0.86\n\n## 怎么开始\n\n- `pip install oxylabs-ai-studio` 证据：`readme.md` Claim：`clm_0003` supported 0.86\n\n## 继续前判断卡\n\n- **当前建议**：仅建议沙盒试装\n- **为什么**：项目存在安装命令、宿主配置或本地写入线索，不建议直接进入主力环境，应先在隔离环境试装。\n\n### 30 秒判断\n\n- **现在怎么做**：仅建议沙盒试装\n- **最小安全下一步**：先跑 Prompt Preview；若仍要安装，只在隔离环境试装\n- **先别相信**：真实输出质量不能在安装前相信。\n- **继续会触碰**：命令执行、本地环境或项目文件、宿主 AI 上下文\n\n### 现在可以相信\n\n- **能力存在：命令行启动或安装流程**（supported）：可以相信项目包含这类能力线索；是否适合你的具体任务仍要试用或安装后验证。 证据：`readme.md` Claim：`clm_0001` supported 0.86\n- **存在 Quick Start / 安装命令线索**（supported）：可以相信项目文档出现过启动或安装入口；不要因此直接在主力环境运行。 证据：`readme.md` Claim：`clm_0003` supported 0.86\n\n### 现在还不能相信\n\n- **真实输出质量不能在安装前相信。**（unverified）：Prompt Preview 只能展示引导方式，不能证明真实项目中的结果质量。\n- **宿主 AI 版本兼容性不能在安装前相信。**（unverified）：Claude、Cursor、Codex、Gemini 等宿主加载规则和版本差异必须在真实环境验证。\n- **不会污染现有宿主 AI 行为，不能直接相信。**（inferred）：Skill、plugin、AGENTS/CLAUDE/GEMINI 指令可能改变宿主 AI 的默认行为。\n- **可安全回滚不能默认相信。**（unverified）：除非项目明确提供卸载和恢复说明，否则必须先在隔离环境验证。\n- **真实安装后是否与用户当前宿主 AI 版本兼容？**（unverified）：兼容性只能通过实际宿主环境验证。\n- **项目输出质量是否满足用户具体任务？**（unverified）：安装前预览只能展示流程和边界，不能替代真实评测。\n- **安装命令是否需要网络、权限或全局写入？**（unverified）：这影响企业环境和个人环境的安装风险。 证据：`readme.md`\n\n### 继续会触碰什么\n\n- **命令执行**：包管理器、网络下载、本地插件目录、项目配置或用户主目录。 原因：运行第一条命令就可能产生环境改动；必须先判断是否值得跑。 证据：`readme.md`\n- **本地环境或项目文件**：安装结果、插件缓存、项目配置或本地依赖目录。 原因：安装前无法证明写入范围和回滚方式，需要隔离验证。 证据：`readme.md`\n- **宿主 AI 上下文**：AI Context Pack、Prompt Preview、Skill 路由、风险规则和项目事实。 原因：导入上下文会影响宿主 AI 后续判断，必须避免把未验证项包装成事实。\n\n### 最小安全下一步\n\n- **先跑 Prompt Preview**：用安装前交互式试用判断工作方式是否匹配，不需要授权或改环境。（适用：任何项目都适用，尤其是输出质量未知时。）\n- **只在隔离目录或测试账号试装**：避免安装命令污染主力宿主 AI、真实项目或用户主目录。（适用：存在命令执行、插件配置或本地写入线索时。）\n- **安装后只验证一个最小任务**：先验证加载、兼容、输出质量和回滚，再决定是否深用。（适用：准备从试用进入真实工作流时。）\n\n### 退出方式\n\n- **保留安装前状态**：记录原始宿主配置和项目状态，后续才能判断是否可恢复。\n- **记录安装命令和写入路径**：没有明确卸载说明时，至少要知道哪些目录或配置需要手动清理。\n- **如果没有回滚路径，不进入主力环境**：不可回滚是继续前阻断项，不应靠信任或运气继续。\n\n## 哪些只能预览\n\n- 解释项目适合谁和能做什么\n- 基于项目文档演示典型对话流程\n- 帮助用户判断是否值得安装或继续研究\n\n## 哪些必须安装后验证\n\n- 真实安装 Skill、插件或 CLI\n- 执行脚本、修改本地文件或访问外部服务\n- 验证真实输出质量、性能和兼容性\n\n## 边界与风险判断卡\n\n- **把安装前预览误认为真实运行**：用户可能高估项目已经完成的配置、权限和兼容性验证。 处理方式：明确区分 prompt_preview_can_do 与 runtime_required。 Claim：`clm_0004` inferred 0.45\n- **命令执行会修改本地环境**：安装命令可能写入用户主目录、宿主插件目录或项目配置。 处理方式：先在隔离环境或测试账号中运行。 证据：`readme.md` Claim：`clm_0005` supported 0.86\n- **待确认**：真实安装后是否与用户当前宿主 AI 版本兼容？。原因：兼容性只能通过实际宿主环境验证。\n- **待确认**：项目输出质量是否满足用户具体任务？。原因：安装前预览只能展示流程和边界，不能替代真实评测。\n- **待确认**：安装命令是否需要网络、权限或全局写入？。原因：这影响企业环境和个人环境的安装风险。\n\n## 开工前工作上下文\n\n### 加载顺序\n\n- 先读取 how_to_use.host_ai_instruction，建立安装前判断资产的边界。\n- 读取 claim_graph_summary，确认事实来自 Claim/Evidence Graph，而不是 Human Wiki 叙事。\n- 再读取 intended_users、capabilities 和 quick_start_candidates，判断用户是否匹配。\n- 需要执行具体任务时，优先查 role_skill_index，再查 evidence_index。\n- 遇到真实安装、文件修改、网络访问、性能或兼容性问题时，转入 risk_card 和 boundaries.runtime_required。\n\n### 任务路由\n\n- **命令行启动或安装流程**：先说明这是安装后验证能力，再给出安装前检查清单。 边界：必须真实安装或运行后验证。 证据：`readme.md` Claim：`clm_0001` supported 0.86\n\n### 上下文规模\n\n- 文件总数：29\n- 重要文件覆盖：17/29\n- 证据索引条目：17\n- 角色 / Skill 条目：2\n\n### 证据不足时的处理\n\n- **missing_evidence**：说明证据不足，要求用户提供目标文件、README 段落或安装后验证记录；不要补全事实。\n- **out_of_scope_request**：说明该任务超出当前 AI Context Pack 证据范围，并建议用户先查看 Human Manual 或真实安装后验证。\n- **runtime_request**：给出安装前检查清单和命令来源，但不要替用户执行命令或声称已执行。\n- **source_conflict**：同时展示冲突来源，标记为待核实，不要强行选择一个版本。\n\n## Prompt Recipes\n\n### 适配判断\n\n- 目标：判断这个项目是否适合用户当前任务。\n- 预期输出：适配结论、关键理由、证据引用、安装前可预览内容、必须安装后验证内容、下一步建议。\n\n```text\n请基于 oxylabs-ai-studio-py 的 AI Context Pack，先问我 3 个必要问题，然后判断它是否适合我的任务。回答必须包含：适合谁、能做什么、不能做什么、是否值得安装、证据来自哪里。所有项目事实必须引用 evidence_refs、source_paths 或 claim_id。\n```\n\n### 安装前体验\n\n- 目标：让用户在安装前感受核心工作流，同时避免把预览包装成真实能力或营销承诺。\n- 预期输出：一段带边界标签的体验剧本、安装后验证清单和谨慎建议；不含真实运行承诺或强营销表述。\n\n```text\n请把 oxylabs-ai-studio-py 当作安装前体验资产，而不是已安装工具或真实运行环境。\n\n请严格输出四段：\n1. 先问我 3 个必要问题。\n2. 给出一段“体验剧本”：用 [安装前可预览]、[必须安装后验证]、[证据不足] 三种标签展示它可能如何引导工作流。\n3. 给出安装后验证清单：列出哪些能力只有真实安装、真实宿主加载、真实项目运行后才能确认。\n4. 给出谨慎建议：只能说“值得继续研究/试装”“先补充信息后再判断”或“不建议继续”，不得替项目背书。\n\n硬性边界：\n- 不要声称已经安装、运行、执行测试、修改文件或产生真实结果。\n- 不要写“自动适配”“确保通过”“完美适配”“强烈建议安装”等承诺性表达。\n- 如果描述安装后的工作方式，必须使用“如果安装成功且宿主正确加载 Skill，它可能会……”这种条件句。\n- 体验剧本只能写成“示例台词/假设流程”：使用“可能会询问/可能会建议/可能会展示”，不要写“已写入、已生成、已通过、正在运行、正在生成”。\n- Prompt Preview 不负责给安装命令；如用户准备试装，只能提示先阅读 Quick Start 和 Risk Card，并在隔离环境验证。\n- 所有项目事实必须来自 supported claim、evidence_refs 或 source_paths；inferred/unverified 只能作风险或待确认项。\n\n```\n\n### 角色 / Skill 选择\n\n- 目标：从项目里的角色或 Skill 中挑选最匹配的资产。\n- 预期输出：候选角色或 Skill 列表，每项包含适用场景、证据路径、风险边界和是否需要安装后验证。\n\n```text\n请读取 role_skill_index，根据我的目标任务推荐 3-5 个最相关的角色或 Skill。每个推荐都要说明适用场景、可能输出、风险边界和 evidence_refs。\n```\n\n### 风险预检\n\n- 目标：安装或引入前识别环境、权限、规则冲突和质量风险。\n- 预期输出：环境、权限、依赖、许可、宿主冲突、质量风险和未知项的检查清单。\n\n```text\n请基于 risk_card、boundaries 和 quick_start_candidates，给我一份安装前风险预检清单。不要替我执行命令，只说明我应该检查什么、为什么检查、失败会有什么影响。\n```\n\n### 宿主 AI 开工指令\n\n- 目标：把项目上下文转成一次对话开始前的宿主 AI 指令。\n- 预期输出：一段边界明确、证据引用明确、适合复制给宿主 AI 的开工前指令。\n\n```text\n请基于 oxylabs-ai-studio-py 的 AI Context Pack，生成一段我可以粘贴给宿主 AI 的开工前指令。这段指令必须遵守 not_runtime=true，不能声称项目已经安装、运行或产生真实结果。\n```\n\n\n## 角色 / Skill 索引\n\n- 共索引 2 个角色 / Skill / 项目文档条目。\n\n- **OxyLabs AI Studio Python SDK**（project_doc）：! AI-Studio Python 1 https://github.com/oxylabs/oxylabs-ai-studio-py/blob/main/Ai-Studio2.png https://aistudio.oxylabs.io/?utm source=877&utm medium=affiliate&utm campaign=ai studio&groupid=877&utm content=ai-studio-js-github&transaction id=102f49063ab94276ae8f116d224b67 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`readme.md`\n- **Oxylabs AI Studio Python SDK Agentic Code Guide**（project_doc）：Oxylabs AI Studio Python SDK Agentic Code Guide 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`agentic_code_guide.md`\n\n## 证据索引\n\n- 共索引 17 条证据。\n\n- **OxyLabs AI Studio Python SDK**（documentation）：! AI-Studio Python 1 https://github.com/oxylabs/oxylabs-ai-studio-py/blob/main/Ai-Studio2.png https://aistudio.oxylabs.io/?utm source=877&utm medium=affiliate&utm campaign=ai studio&groupid=877&utm content=ai-studio-js-github&transaction id=102f49063ab94276ae8f116d224b67 证据：`readme.md`\n- **License**（source_file）：Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files the \"Software\" , to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: 证据：`LICENSE`\n- **Oxylabs AI Studio Python SDK Agentic Code Guide**（documentation）：Oxylabs AI Studio Python SDK Agentic Code Guide 证据：`agentic_code_guide.md`\n- **Python-generated files**（source_file）：Python-generated files pycache / .py oc build/ dist/ wheels/ .egg-info 证据：`.gitignore`\n- **Ai Map**（source_file）：from oxylabs ai studio.apps.ai map import AiMap 证据：`examples/ai_map.py`\n- **Browser Agent**（source_file）：from oxylabs ai studio.apps.browser agent import BrowserAgent 证据：`examples/browser_agent.py`\n- **Crawl Generated Schema**（source_file）：from oxylabs ai studio.apps.ai crawler import AiCrawler 证据：`examples/crawl_generated_schema.py`\n- **Crawl Markdown**（source_file）：from oxylabs ai studio.apps.ai crawler import AiCrawler 证据：`examples/crawl_markdown.py`\n- **Crawl Pydantic Schema**（source_file）：from pydantic import BaseModel, Field from oxylabs ai studio.apps.ai crawler import AiCrawler 证据：`examples/crawl_pydantic_schema.py`\n- **Scrape Generated Schema**（source_file）：from oxylabs ai studio.apps.ai scraper import AiScraper 证据：`examples/scrape_generated_schema.py`\n- **Scrape Markdown**（source_file）：from oxylabs ai studio.apps.ai scraper import AiScraper 证据：`examples/scrape_markdown.py`\n- **Scrape Pydantic Schema**（source_file）：from pydantic import BaseModel from oxylabs ai studio.apps.ai scraper import AiScraper 证据：`examples/scrape_pydantic_schema.py`\n- **Search Instant**（source_file）：from oxylabs ai studio.apps.ai search import AiSearch 证据：`examples/search_instant.py`\n- **Search No Content**（source_file）：from oxylabs ai studio.apps.ai search import AiSearch 证据：`examples/search_no_content.py`\n- **Search With Content**（source_file）：from oxylabs ai studio.apps.ai search import AiSearch 证据：`examples/search_with_content.py`\n- **Makefile**（source_file）：lint: @uv run ruff format ./src @uv run ruff check ./src --fix @uv run mypy ./src 证据：`makefile`\n- **default**（source_file）：project name = \"oxylabs-ai-studio\" version = \"0.2.20\" description = \"Oxylabs studio python sdk\" readme = \"readme.md\" keywords = \"oxylabs\", \"ai\", \"studio\" requires-python = \" =3.10\" dependencies = \"httpx =0.28.1\", \"pydantic =2.0.0\", \"pydantic-settings =2.9.1\", \"python-dotenv =1.1.0\", \"tenacity =9.1.2\", 证据：`pyproject.toml`\n\n## 宿主 AI 必须遵守的规则\n\n- **把本资产当作开工前上下文，而不是运行环境。**：AI Context Pack 只包含证据化项目理解，不包含目标项目的可执行状态。 证据：`readme.md`, `LICENSE`, `agentic_code_guide.md`\n- **回答用户时区分可预览内容与必须安装后才能验证的内容。**：安装前体验的消费者价值来自降低误装和误判，而不是伪装成真实运行。 证据：`readme.md`, `LICENSE`, `agentic_code_guide.md`\n\n## 用户开工前应该回答的问题\n\n- 你准备在哪个宿主 AI 或本地环境中使用它？\n- 你只是想先体验工作流，还是准备真实安装？\n- 你最在意的是安装成本、输出质量、还是和现有规则的冲突？\n\n## 验收标准\n\n- 所有能力声明都能回指到 evidence_refs 中的文件路径。\n- AI_CONTEXT_PACK.md 没有把预览包装成真实运行。\n- 用户能在 3 分钟内看懂适合谁、能做什么、如何开始和风险边界。\n\n---\n\n## Doramagic Context Augmentation\n\n下面内容用于强化 Repomix/AI Context Pack 主体。Human Manual 只提供阅读骨架；踩坑日志会被转成宿主 AI 必须遵守的工作约束。\n\n## Human Manual 骨架\n\n使用规则：这里只是项目阅读路线和显著性信号，不是事实权威。具体事实仍必须回到 repo evidence / Claim Graph。\n\n宿主 AI 硬性规则：\n- 不得把页标题、章节顺序、摘要或 importance 当作项目事实证据。\n- 解释 Human Manual 骨架时，必须明确说它只是阅读路线/显著性信号。\n- 能力、安装、兼容性、运行状态和风险判断必须引用 repo evidence、source path 或 Claim Graph。\n\n- **项目介绍**：importance `high`\n - source_paths: readme.md, pyproject.toml\n- **快速入门**：importance `high`\n - source_paths: pyproject.toml, src/oxylabs_ai_studio/settings.py, src/oxylabs_ai_studio/__init__.py\n- **AI-Scraper 文档**：importance `high`\n - source_paths: src/oxylabs_ai_studio/apps/ai_scraper.py, examples/scrape_markdown.py, examples/scrape_pydantic_schema.py, examples/scrape_generated_schema.py\n- **AI-Crawler 文档**：importance `high`\n - source_paths: src/oxylabs_ai_studio/apps/ai_crawler.py, examples/crawl_markdown.py, examples/crawl_pydantic_schema.py, examples/crawl_generated_schema.py\n- **AI-Search 文档**：importance `medium`\n - source_paths: src/oxylabs_ai_studio/apps/ai_search.py, examples/search_with_content.py, examples/search_no_content.py, examples/search_instant.py\n- **AI-Map 文档**：importance `medium`\n - source_paths: src/oxylabs_ai_studio/apps/ai_map.py, examples/ai_map.py\n- **Browser Agent 文档**：importance `medium`\n - source_paths: src/oxylabs_ai_studio/apps/browser_agent.py, examples/browser_agent.py\n- **API 客户端架构**：importance `high`\n - source_paths: src/oxylabs_ai_studio/client.py, src/oxylabs_ai_studio/logger.py, src/oxylabs_ai_studio/settings.py, src/oxylabs_ai_studio/utils.py\n\n## Repo Inspection Evidence / 源码检查证据\n\n- repo_clone_verified: false\n- repo_inspection_verified: false\n- repo_commit: `unknown`\n\n宿主 AI 硬性规则：\n- 没有 repo_clone_verified=true 时，不得声称已经读过源码。\n- 没有 repo_inspection_verified=true 时，不得把 README/docs/package 文件判断写成事实。\n- 没有 quick_start_verified=true 时，不得声称 Quick Start 已跑通。\n\n## Doramagic Pitfall Constraints / 踩坑约束\n\n这些规则来自 Doramagic 发现、验证或编译过程中的项目专属坑点。宿主 AI 必须把它们当作工作约束，而不是普通说明文字。\n\n### Constraint 1: 仓库名和安装名不一致\n\n- Trigger: 仓库名 `oxylabs-ai-studio-py` 与安装入口 `oxylabs-ai-studio` 不完全一致。\n- Host AI rule: 在 npm/PyPI/GitHub 上确认包名映射和官方 README 说明。\n- Why it matters: 用户照着仓库名搜索包或照着包名找仓库时容易走错入口。\n- Evidence: identity.distribution | github_repo:1003630893 | https://github.com/oxylabs/oxylabs-ai-studio-py | repo=oxylabs-ai-studio-py; install=oxylabs-ai-studio\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 2: 能力判断依赖假设\n\n- Trigger: README/documentation is current enough for a first validation pass.\n- Host AI rule: 将假设转成下游验证清单。\n- Why it matters: 假设不成立时，用户拿不到承诺的能力。\n- Evidence: capability.assumptions | github_repo:1003630893 | https://github.com/oxylabs/oxylabs-ai-studio-py | README/documentation is current enough for a first validation pass.\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 3: 来源证据：v.0.2.19\n\n- Trigger: GitHub 社区证据显示该项目存在一个维护/版本相关的待验证问题：v.0.2.19\n- Host AI rule: 来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- Why it matters: 可能影响升级、迁移或版本选择。\n- Evidence: community_evidence:github | cevd_96a2e22cbea94aac8c2788f763ce7c04 | https://github.com/oxylabs/oxylabs-ai-studio-py/releases/tag/v0.2.19 | 来源类型 github_release 暴露的待验证使用条件。\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 4: 维护活跃度未知\n\n- Trigger: 未记录 last_activity_observed。\n- Host AI rule: 补 GitHub 最近 commit、release、issue/PR 响应信号。\n- Why it matters: 新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。\n- Evidence: evidence.maintainer_signals | github_repo:1003630893 | https://github.com/oxylabs/oxylabs-ai-studio-py | last_activity_observed missing\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 5: 下游验证发现风险项\n\n- Trigger: no_demo\n- Host AI rule: 进入安全/权限治理复核队列。\n- Why it matters: 下游已经要求复核，不能在页面中弱化。\n- Evidence: downstream_validation.risk_items | github_repo:1003630893 | https://github.com/oxylabs/oxylabs-ai-studio-py | no_demo; severity=medium\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 6: 存在安全注意事项\n\n- Trigger: No sandbox install has been executed yet; downstream must verify before user use.\n- Host AI rule: 转成明确权限清单和安全审查提示。\n- Why it matters: 用户安装前需要知道权限边界和敏感操作。\n- Evidence: risks.safety_notes | github_repo:1003630893 | https://github.com/oxylabs/oxylabs-ai-studio-py | No sandbox install has been executed yet; downstream must verify before user use.\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 7: 存在评分风险\n\n- Trigger: no_demo\n- Host AI rule: 把风险写入边界卡，并确认是否需要人工复核。\n- Why it matters: 风险会影响是否适合普通用户安装。\n- Evidence: risks.scoring_risks | github_repo:1003630893 | https://github.com/oxylabs/oxylabs-ai-studio-py | no_demo; severity=medium\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 8: issue/PR 响应质量未知\n\n- Trigger: issue_or_pr_quality=unknown。\n- Host AI rule: 抽样最近 issue/PR，判断是否长期无人处理。\n- Why it matters: 用户无法判断遇到问题后是否有人维护。\n- Evidence: evidence.maintainer_signals | github_repo:1003630893 | https://github.com/oxylabs/oxylabs-ai-studio-py | issue_or_pr_quality=unknown\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 9: 发布节奏不明确\n\n- Trigger: release_recency=unknown。\n- Host AI rule: 确认最近 release/tag 和 README 安装命令是否一致。\n- Why it matters: 安装命令和文档可能落后于代码，用户踩坑概率升高。\n- Evidence: evidence.maintainer_signals | github_repo:1003630893 | https://github.com/oxylabs/oxylabs-ai-studio-py | release_recency=unknown\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n",
"summary": "给宿主 AI 的上下文和工作边界。",
"title": "AI Context Pack / 带给我的 AI"
},
"boundary_risk_card": {
"asset_id": "boundary_risk_card",
"filename": "BOUNDARY_RISK_CARD.md",
"markdown": "# Boundary & Risk Card / 安装前决策卡\n\n项目：oxylabs/oxylabs-ai-studio-py\n\n## Doramagic 试用结论\n\n当前结论：可以进入发布前推荐检查；首次使用仍应从最小权限、临时目录和可回滚配置开始。\n\n## 用户现在可以做\n\n- 可以先阅读 Human Manual，理解项目目的和主要工作流。\n- 可以复制 Prompt Preview 做安装前体验；这只验证交互感，不代表真实运行。\n- 可以把官方 Quick Start 命令放到隔离环境中验证，不要直接进主力环境。\n\n## 现在不要做\n\n- 不要把 Prompt Preview 当成项目实际运行结果。\n- 不要把 metadata-only validation 当成沙箱安装验证。\n- 不要把未验证能力写成“已支持、已跑通、可放心安装”。\n- 不要在首次试用时交出生产数据、私人文件、真实密钥或主力配置目录。\n\n## 安装前检查\n\n- 宿主 AI 是否匹配：local_cli\n- 官方安装入口状态：已发现官方入口\n- 是否在临时目录、临时宿主或容器中验证：必须是\n- 是否能回滚配置改动：必须能\n- 是否需要 API Key、网络访问、读写文件或修改宿主配置：未确认前按高风险处理\n- 是否记录了安装命令、实际输出和失败日志：必须记录\n\n## 当前阻塞项\n\n- review_required: community_discussion_evidence_below_public_threshold\n\n## 项目专属踩坑\n\n- 仓库名和安装名不一致（medium）：用户照着仓库名搜索包或照着包名找仓库时容易走错入口。 建议检查：在 npm/PyPI/GitHub 上确认包名映射和官方 README 说明。\n- 能力判断依赖假设（medium）：假设不成立时，用户拿不到承诺的能力。 建议检查：将假设转成下游验证清单。\n- 来源证据：v.0.2.19（medium）：可能影响升级、迁移或版本选择。 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 维护活跃度未知（medium）：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。 建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。\n- 下游验证发现风险项（medium）：下游已经要求复核，不能在页面中弱化。 建议检查：进入安全/权限治理复核队列。\n\n## 风险与权限提示\n\n- no_demo: medium\n\n## 证据缺口\n\n- 暂未发现结构化证据缺口。\n",
"summary": "安装、权限、验证和推荐前风险。",
"title": "Boundary & Risk Card / 边界与风险卡"
},
"human_manual": {
"asset_id": "human_manual",
"filename": "HUMAN_MANUAL.md",
"markdown": "# https://github.com/oxylabs/oxylabs-ai-studio-py 项目说明书\n\n生成时间：2026-05-14 00:55:26 UTC\n\n## 目录\n\n- [项目介绍](#introduction)\n- [快速入门](#quick-start)\n- [AI-Scraper 文档](#ai-scraper)\n- [AI-Crawler 文档](#ai-crawler)\n- [AI-Search 文档](#ai-search)\n- [AI-Map 文档](#ai-map)\n- [Browser Agent 文档](#browser-agent)\n- [API 客户端架构](#api-client)\n- [数据模型](#data-models)\n- [Schema 生成指南](#schema-generation)\n\n\n\n## 项目介绍\n\n### 相关页面\n\n相关主题：[快速入门](#quick-start), [AI-Scraper 文档](#ai-scraper), [AI-Crawler 文档](#ai-crawler)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [readme.md](https://github.com/oxylabs/oxylabs-ai-studio-py/blob/main/readme.md)\n- [agentic_code_guide.md](https://github.com/oxylabs/oxylabs-ai-studio-py/blob/main/agentic_code_guide.md)\n- [src/oxylabs_ai_studio/apps/ai_search.py](https://github.com/oxylabs/oxylabs-ai-studio-py/blob/main/src/oxylabs_ai_studio/apps/ai_search.py)\n- [src/oxylabs_ai_studio/apps/ai_crawler.py](https://github.com/oxylabs/oxylabs-ai-studio-py/blob/main/src/oxylabs_ai_studio/apps/ai_crawler.py)\n- [src/oxylabs_ai_studio/apps/ai_scraper.py](https://github.com/oxylabs/oxylabs-ai-studio-py/blob/main/src/oxylabs_ai_studio/apps/ai_scraper.py)\n- [src/oxylabs_ai_studio/apps/ai_map.py](https://github.com/oxylabs/oxylabs-ai-studio-py/blob/main/src/oxylabs_ai_studio/apps/ai_map.py)\n- [src/oxylabs_ai_studio/apps/browser_agent.py](https://github.com/oxylabs/oxylabs-ai-studio-py/blob/main/src/oxylabs_ai_studio/apps/browser_agent.py)\n- [examples/scrape_markdown.py](https://github.com/oxylabs/oxylabs-ai-studio-py/blob/main/examples/scrape_markdown.py)\n- [examples/crawl_generated_schema.py](https://github.com/oxylabs/oxylabs-ai-studio-py/blob/main/examples/crawl_generated_schema.py)\n- [examples/scrape_generated_schema.py](https://github.com/oxylabs/oxylabs-ai-studio-py/blob/main/examples/scrape_generated_schema.py)\n \n\n# 项目介绍\n\n## 项目概述\n\nOxylabs AI Studio Python SDK（`oxylabs-ai-studio`）是一个用于与 [Oxylabs AI Studio API](https://aistudio.oxylabs.io/) 服务无缝交互的 Python 客户端库。该 SDK 提供了对多种 AI 驱动数据提取工具的访问，包括 AI-Scraper、AI-Crawler、AI-Browser-Agent 等。 资料来源：[readme.md:1-8]()\n\n### 核心特性\n\n- **多应用支持**：集成爬虫、搜索、映射等多种数据提取功能\n- **同步/异步接口**：同时支持同步和异步编程模式\n- **结构化输出**：支持 JSON、Markdown、CSV、Screenshot 等多种输出格式\n- **Schema 生成**：内置 AI 驱动的 Schema 自动生成功能\n- **地理位置定位**：支持全球代理位置定位\n- **JavaScript 渲染**：可选的 JavaScript 渲染支持\n\n## 系统架构\n\n### 整体架构图\n\n```mermaid\ngraph TD\n A[用户应用] --> B[oxylabs-ai-studio SDK]\n B --> C[AiCrawler]\n B --> D[AiScraper]\n B --> E[AiSearch]\n B --> F[AiMap]\n B --> G[BrowserAgent]\n C --> H[Oxylabs AI Studio API]\n D --> H\n E --> H\n F --> H\n G --> H\n H --> I[SERP / Web Content]\n```\n\n### 模块组成\n\n| 模块 | 功能描述 | 主要方法 |\n|------|---------|---------|\n| AiCrawler | 网站爬虫，按深度遍历页面 | `crawl()`, `crawl_async()` |\n| AiScraper | 单页面内容抓取 | `scrape()`, `scrape_async()` |\n| AiSearch | 搜索引擎结果获取 | `search()`, `instant_search()` |\n| AiMap | 网站结构映射 | `map()`, `map_async()` |\n| BrowserAgent | 浏览器代理操作 | `run()`, `run_async()` |\n\n## 安装与配置\n\n### 环境要求\n\n- Python 3.10 及以上版本\n- 有效的 Oxylabs API 密钥\n\n### 安装方式\n\n```bash\npip install oxylabs-ai-studio\n```\n\n资料来源：[readme.md:13]()\n\n### 初始化配置\n\n所有应用模块的初始化方式相同，需要提供 API 密钥：\n\n```python\nfrom oxylabs_ai_studio.apps.ai_crawler import AiCrawler\n\ncrawler = AiCrawler(api_key=\"\")\n```\n\n## 应用模块详解\n\n### AI-Crawler（网站爬虫）\n\n#### 功能说明\n\nAiCrawler 模块用于深度爬取整个网站或指定路径下的所有相关页面，支持用户自定义的自然语言提示来指导提取过程。 资料来源：[readme.md:27-28]()\n\n#### 同步接口\n\n```python\nfrom oxylabs_ai_studio.apps.ai_crawler import AiCrawler\n\ncrawler = AiCrawler(api_key=\"\")\n\nurl = \"https://oxylabs.io\"\nresult = crawler.crawl(\n url=url,\n user_prompt=\"Find all pages with proxy products pricing\",\n output_format=\"markdown\",\n render_javascript=False,\n return_sources_limit=3,\n geo_location=\"United States\",\n)\nprint(\"Results:\")\nfor item in result.data:\n print(item, \"\\n\")\n```\n\n资料来源：[readme.md:27-42]()\n\n#### 参数说明\n\n| 参数 | 类型 | 必填 | 默认值 | 说明 |\n|------|------|------|--------|------|\n| url | str | 是 | - | 爬取的起始 URL |\n| user_prompt | str | 是 | - | 指导提取的自然语言提示 |\n| output_format | Literal | 否 | \"markdown\" | 输出格式：json/markdown/csv/toon |\n| schema | dict | 否 | None | JSON Schema（json/csv/toon 格式时必填） |\n| render_javascript | bool | 否 | False | 是否渲染 JavaScript |\n| return_sources_limit | int | 否 | 25 | 返回结果数量上限 |\n| geo_location | str | 否 | None | 代理位置（ISO2 格式或国家名称） |\n| max_credits | int | 否 | None | 最大消耗积分 |\n\n资料来源：[readme.md:43-51]()\n\n### AI-Scraper（页面抓取）\n\n#### 功能说明\n\nAiScraper 专注于单页面内容抓取，可返回 Markdown 格式内容或根据用户提供的 JSON Schema 返回结构化数据。 资料来源：[agentic_code_guide.md:62-66]()\n\n#### 同步接口\n\n```python\nfrom oxylabs_ai_studio.apps.ai_scraper import AiScraper\n\nscraper = AiScraper(api_key=\"\")\n\nschema = scraper.generate_schema(prompt=\"want to parse developer, platform, type, price game title, genre (array) and description\")\nprint(f\"Generated schema: {schema}\")\n\nurl = \"https://sandbox.oxylabs.io/products/3\"\nresult = scraper.scrape(\n url=url,\n output_format=\"json\",\n schema=schema,\n render_javascript=False,\n)\nprint(result)\n```\n\n资料来源：[readme.md:81-95]()\n\n#### 异步接口\n\n```python\nimport asyncio\nfrom oxylabs_ai_studio.apps.ai_scraper import AiScraper\n\nscraper = AiScraper(api_key=\"\")\n\nasync def main():\n url = \"https://sandbox.oxylabs.io/products/3\"\n result = await scraper.scrape_async(\n url=url,\n output_format=\"json\",\n schema={\"type\": \"object\", \"properties\": {\"price\": {\"type\": \"string\"}}, \"required\": []},\n render_javascript=False,\n )\n print(result)\n\nif __name__ == \"__main__\":\n asyncio.run(main())\n```\n\n资料来源：[agentic_code_guide.md:68-86]()\n\n#### 参数说明\n\n| 参数 | 类型 | 必填 | 默认值 | 说明 |\n|------|------|------|--------|------|\n| url | str | 是 | - | 目标抓取 URL |\n| output_format | Literal | 否 | \"markdown\" | 输出格式：json/markdown/csv/screenshot/toon |\n| schema | dict | 否 | None | JSON Schema（json/csv/toon 格式时必填） |\n| render_javascript | bool/string | 否 | False | JavaScript 渲染，支持 \"auto\" 自动检测 |\n| geo_location | str | 否 | None | 代理位置 |\n| max_credits | int | 否 | None | 最大消耗积分 |\n\n#### 返回数据结构\n\n```python\nclass AiScraperJob(BaseModel):\n run_id: str\n message: str | None = None\n data: str | dict | None\n```\n\n- output_format 为 \"json\" 时：data 为字典\n- output_format 为 \"markdown\" 时：data 为字符串\n- output_format 为 \"csv\" 时：data 为 CSV 格式字符串\n- output_format 为 \"screenshot\" 时：data 为字符串（Base64 或 URL）\n\n资料来源：[agentic_code_guide.md:87-101]()\n\n### AI-Search（搜索引擎）\n\n#### 功能说明\n\nAiSearch 提供搜索引擎结果获取功能，支持标准搜索和即时搜索两种模式。即时搜索在 `limit <= 10` 且 `return_content=False` 时自动启用，提供更快的响应。 资料来源：[readme.md:10-24]()\n\n#### 标准搜索\n\n```python\nfrom oxylabs_ai_studio.apps.ai_search import AiSearch\n\nsearch = AiSearch(api_key=\"\")\n\nquery = \"lasagna recipe\"\nresult = search.search(\n query=query,\n limit=5,\n render_javascript=False,\n return_content=True,\n)\nprint(result.data)\n```\n\n资料来源：[readme.md:10-24]()\n\n#### 即时搜索\n\n```python\nresult = search.instant_search(\n query=query,\n limit=10,\n)\nprint(result.data)\n```\n\n#### 参数说明\n\n| 参数 | 类型 | 必填 | 默认值 | 说明 |\n|------|------|------|--------|------|\n| query | str | 是 | - | 搜索关键词 |\n| limit | int | 否 | 10 | 返回结果数量（最大 50） |\n| render_javascript | bool | 否 | False | 是否渲染 JavaScript |\n| return_content | bool | 否 | True | 是否返回 Markdown 内容 |\n| geo_location | str | 否 | None | 地理位置定位 |\n\n#### 即时搜索限制\n\n- 最大 limit 为 10\n- 仅支持 query、limit、geo_location 三个参数\n\n资料来源：[readme.md:17-24]()\n\n### AI-Map（网站映射）\n\n#### 功能说明\n\nAiMap 用于快速映射网站结构，通过关键词搜索定位相关页面。 资料来源：[readme.md:54-70]()\n\n#### 使用示例\n\n```python\nfrom oxylabs_ai_studio.apps.ai_map import AiMap\n\nai_map = AiMap(api_key=\"\")\npayload = {\n \"url\": \"https://career.oxylabs.io\",\n \"search_keywords\": [\"career\", \"jobs\", \"vacancy\"],\n \"user_prompt\": \"job ad pages\",\n \"max_crawl_depth\": 2,\n \"limit\": 10,\n \"geo_location\": \"Germany\",\n \"render_javascript\": False,\n \"include_sitemap\": True,\n}\nresult = ai_map.map(**payload)\nprint(result.data)\n```\n\n#### 参数说明\n\n| 参数 | 类型 | 必填 | 默认值 | 说明 |\n|------|------|------|--------|------|\n| url | str | 是 | - | 目标网站 URL |\n| search_keywords | list[str] | 否 | [] | 搜索关键词列表 |\n| user_prompt | str | 否 | None | 自然语言提示 |\n| max_crawl_depth | int | 否 | 1 | 最大爬取深度 |\n| limit | int | 否 | 25 | 返回结果数量上限 |\n| geo_location | str | 否 | None | 代理位置 |\n| render_javascript | bool | 否 | False | 是否渲染 JavaScript |\n| include_sitemap | bool | 否 | True | 是否包含站点地图 |\n| allow_subdomains | bool | 否 | False | 允许子域名 |\n| allow_external_domains | bool | 否 | False | 允许外部域名 |\n| max_credits | int | 否 | None | 最大消耗积分 |\n\n资料来源：[src/oxylabs_ai_studio/apps/ai_map.py:62-75]()\n\n### Browser-Agent（浏览器代理）\n\n#### 功能说明\n\nBrowserAgent 提供浏览器级别的自动化操作能力，可以执行复杂的用户交互任务，如点击、滚动、表单填写等，通过自然语言提示指导操作过程。 资料来源：[agentic_code_guide.md:16-27]()\n\n#### 同步接口\n\n```python\nfrom oxylabs_ai_studio.apps.browser_agent import BrowserAgent\n\nbrowser_agent = BrowserAgent(api_key=\"\")\n\nresult = browser_agent.run(\n url=\"https://sandbox.oxylabs.io/\",\n user_prompt=\"Find if there is game 'super mario odyssey' in the store.\",\n output_format=\"json\",\n schema={\"type\": \"object\", \"properties\": {\"page_url\": {\"type\": \"string\"}}, \"required\": []},\n)\nprint(result.data)\n```\n\n#### 异步接口\n\n```python\nimport asyncio\nfrom oxylabs_ai_studio.apps.browser_agent import BrowserAgent\n\nbrowser_agent = BrowserAgent(api_key=\"\")\n\nasync def main():\n prompt = \"Find if there is game 'super mario odyssey' in the store.\"\n url = \"https://sandbox.oxylabs.io/\"\n result = await browser_agent.run_async(\n url=url,\n user_prompt=prompt,\n output_format=\"json\",\n schema={\"type\": \"object\", \"properties\": {\"page_url\": {\"type\": \"string\"}}, \"required\": []},\n )\n print(result.data)\n\nif __name__ == \"__main__\":\n asyncio.run(main())\n```\n\n#### 参数说明\n\n| 参数 | 类型 | 必填 | 默认值 | 说明 |\n|------|------|------|--------|------|\n| url | str | 是 | - | 目标 URL |\n| user_prompt | str | 是 | - | 浏览器操作提示（描述任务而非提取内容） |\n| output_format | Literal | 否 | \"markdown\" | 输出格式：json/markdown |\n| schema | dict | 否 | None | JSON Schema（output_format 为 json 时必填） |\n\n#### 返回数据结构\n\n```python\nclass DataModel(BaseModel):\n type: Literal[\"json\", \"markdown\", \"html\", \"screenshot\", \"csv\"]\n content: dict[str, Any] | str | None\n\nclass BrowserAgentJob(BaseModel):\n run_id: str\n message: str | None = None\n data: DataModel | None = None\n```\n\n资料来源：[agentic_code_guide.md:28-48]()\n\n## Schema 生成功能\n\n### 功能概述\n\n所有主要模块都提供了 `generate_schema()` 方法，支持通过自然语言提示自动生成 OpenAPI JSON Schema，实现零配置的快速开发。 资料来源：[examples/scrape_generated_schema.py:1-9]()\n\n### 工作流程\n\n```mermaid\ngraph LR\n A[输入自然语言提示] --> B[调用 API 生成 Schema]\n B --> C[获得 JSON Schema]\n C --> D[用于抓取/爬取任务]\n```\n\n### 使用示例\n\n```python\n# 为爬虫生成 Schema\nschema = crawler.generate_schema(\n prompt=\"proxy plans which have name, price, and features\",\n)\nprint(\"schema: \", schema)\n\n# 为抓取生成 Schema\nschema = scraper.generate_schema(\n prompt=\"want to parse developer, platform, type, price game title, genre (array) and description\"\n)\nprint(f\"Generated schema: {schema}\")\n```\n\n资料来源：[examples/crawl_generated_schema.py:4-13]()\n\n## 使用场景示例\n\n### 电商产品数据提取\n\n#### 场景描述\n\n从电商网站提取产品分类页面的所有产品数据，并获取每个产品的详细信息。 资料来源：[agentic_code_guide.md:103-125]()\n\n#### 推荐工作流\n\n```mermaid\ngraph TD\n A[识别分类页面] --> B[Browser-Agent 定位分类页 URL]\n B --> C[提取分页 URLs]\n C --> D[AI-Scraper 提取产品 URLs]\n D --> E[AI-Scraper 提取产品详情]\n```\n\n#### 实施步骤\n\n1. **定位分类页面**\n - 使用 Browser-Agent 识别分类页面 URL 和所有分页 URL\n - 定义返回分页 URL 的 JSON Schema\n\n2. **提取产品链接**\n - 使用 AI-Scraper 从分页页面提取所有产品 URL\n\n3. **提取产品详情**\n - 使用 AI-Scraper 和预定义的 JSON Schema 提取详细数据\n\n#### 示例 Schema\n\n```json\n{\n \"type\": \"object\",\n \"properties\": {\n \"paginationUrls\": {\n \"type\": \"array\",\n \"description\": \"Return all URLs from first to last page in category pagination. If you noticed there are missing URLs, because category page does not list them all, create them to match existing ones.\",\n \"items\": {\n \"type\": \"string\"\n }\n }\n },\n \"required\": []\n}\n```\n\n资料来源：[agentic_code_guide.md:115-127]()\n\n## 地理位置定位\n\n### 支持格式\n\nSDK 支持多种地理位置指定方式：\n\n| 格式类型 | 示例 | 说明 |\n|---------|------|------|\n| ISO2 格式 | \"US\", \"DE\", \"FR\" | 两字母国家代码 |\n| 国家名称 | \"Germany\", \"United States\" | 标准国家名称（首字母大写） |\n| 坐标格式 | 支持 SERP 定位 | 特定搜索功能使用 |\n\n资料来源：[readme.md:46-48]()\n\n### 使用示例\n\n```python\nresult = scraper.scrape(\n url=\"https://sandbox.oxylabs.io/products/1\",\n output_format=\"markdown\",\n render_javascript=False,\n geo_location=\"Germany\",\n)\n```\n\n## 错误处理与超时\n\n### 超时处理\n\n所有同步方法在超时时会抛出 `TimeoutError` 异常：\n\n```python\ntry:\n result = crawler.crawl(url=\"https://example.com\", ...)\nexcept TimeoutError as e:\n print(f\"爬取超时: {e}\")\n```\n\n### 用户取消\n\n用户可通过键盘中断（Ctrl+C）取消正在执行的任务：\n\n```python\nexcept KeyboardInterrupt:\n logger.info(\"[Cancelled] Request was cancelled by user.\")\n raise KeyboardInterrupt from None\n```\n\n资料来源：[src/oxylabs_ai_studio/apps/ai_crawler.py:89-91]()\n\n## 输出格式对比\n\n| 格式 | 说明 | 适用场景 | 返回类型 |\n|------|------|---------|---------|\n| json | 结构化 JSON 数据 | 需要程序化处理的数据 | dict |\n| markdown | Markdown 格式文本 | 人类可读的内容展示 | str |\n| csv | CSV 表格格式 | 数据表格导出 | str |\n| screenshot | 页面截图 | 视觉验证 | str (Base64/URL) |\n| toon | 结构化表格数据 | 复杂表格结构 | dict |\n\n资料来源：[readme.md:43-44]()\n\n## 依赖关系\n\n### 核心依赖\n\n- **httpx**: 异步 HTTP 客户端，用于 API 通信\n- **pydantic**: 数据验证和模型定义\n\n### 完整依赖列表\n\n请参考项目根目录下的 `pyproject.toml` 文件获取完整的依赖声明。\n\n---\n\n\n\n## 快速入门\n\n### 相关页面\n\n相关主题：[项目介绍](#introduction), [API 客户端架构](#api-client)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [pyproject.toml](https://github.com/oxylabs/oxylabs-ai-studio-py/blob/main/pyproject.toml)\n- [src/oxylabs_ai_studio/settings.py](https://github.com/oxylabs/oxylabs-ai-studio-py/blob/main/src/oxylabs_ai_studio/settings.py)\n- [src/oxylabs_ai_studio/__init__.py](https://github.com/oxylabs/oxylabs-ai-studio-py/blob/main/src/oxylabs_ai_studio/__init__.py)\n- [src/oxylabs_ai_studio/apps/ai_scraper.py](https://github.com/oxylabs/oxylabs-ai-studio-py/blob/main/src/oxylabs_ai_studio/apps/ai_scraper.py)\n- [src/oxylabs_ai_studio/apps/ai_crawler.py](https://github.com/oxylabs/oxylabs-ai-studio-py/blob/main/src/oxylabs_ai_studio/apps/ai_crawler.py)\n- [src/oxylabs_ai_studio/apps/ai_search.py](https://github.com/oxylabs/oxylabs-ai-studio-py/blob/main/src/oxylabs_ai_studio/apps/ai_search.py)\n \n\n# 快速入门\n\n## 概述\n\nOxylabs AI Studio Python SDK（oxylabs-ai-studio-py）是一个用于与 [Oxylabs AI Studio API](https://aistudio.oxylabs.io/) 服务进行交互的 Python SDK。该 SDK 封装了多个 AI 驱动的网页数据提取工具，为开发者提供了简洁的 Python 接口来调用 AI-Scraper、AI-Crawler、AI-Browser-Agent 等服务。资料来源：[readme.md](https://github.com/oxylabs/oxylabs-ai-studio-py/blob/main/readme.md)\n\n## 系统要求\n\n| 要求项 | 规格 |\n|--------|------|\n| Python 版本 | 3.10 及以上 |\n| 外部依赖 | Oxylabs AI Studio API 密钥 |\n| 安装方式 | pip |\n\n资料来源：[readme.md](https://github.com/oxylabs/oxylabs-ai-studio-py/blob/main/readme.md)\n\n## 安装\n\n通过 pip 安装 SDK：\n\n```bash\npip install oxylabs-ai-studio\n```\n\n资料来源：[readme.md](https://github.com/oxylabs/oxylabs-ai-studio-py/blob/main/readme.md)\n\n## 初始化配置\n\n使用 SDK 前，需要实例化相应的应用类并传入 API 密钥：\n\n```python\nfrom oxylabs_ai_studio.apps.ai_scraper import AiScraper\n\nscraper = AiScraper(api_key=\"\")\n```\n\n## SDK 架构\n\n```mermaid\ngraph TD\n A[用户代码] --> B[oxylabs-ai-studio-py SDK]\n B --> C[AiScraper]\n B --> D[AiCrawler]\n B --> E[AiSearch]\n B --> F[BrowserAgent]\n B --> G[AiMap]\n C --> H[Oxylabs AI Studio API]\n D --> H\n E --> H\n F --> H\n G --> H\n```\n\n## 核心应用模块\n\n### AI-Scraper（智能网页抓取）\n\n用于抓取网页内容并返回 Markdown 格式或结构化 JSON 数据。当选择 JSON 输出时，用户需提供有效的 JSON Schema。资料来源：[agentic_code_guide.md](https://github.com/oxylabs/oxylabs-ai-studio-py/blob/main/agentic_code_guide.md)\n\n#### 同步接口示例\n\n```python\nfrom oxylabs_ai_studio.apps.ai_scraper import AiScraper\n\nscraper = AiScraper(api_key=\"\")\n\nurl = \"https://sandbox.oxylabs.io/products/3\"\nresult = scraper.scrape(\n url=url,\n output_format=\"json\",\n schema={\"type\": \"object\", \"properties\": {\"price\": {\"type\": \"string\"}}, \"required\": []},\n render_javascript=False,\n)\nprint(result)\n```\n\n资料来源：[examples/scrape_generated_schema.py](https://github.com/oxylabs/oxylabs-ai-studio-py/blob/main/examples/scrape_generated_schema.py)\n\n#### 异步接口示例\n\n```python\nimport asyncio\nfrom oxylabs_ai_studio.apps.ai_scraper import AiScraper\n\nscraper = AiScraper(api_key=\"\")\n\nasync def main():\n url = \"https://sandbox.oxylabs.io/products/3\"\n result = await scraper.scrape_async(\n url=url,\n output_format=\"json\",\n schema={\"type\": \"object\", \"properties\": {\"price\": {\"type\": \"string\"}}, \"required\": []},\n render_javascript=False,\n )\n print(result)\n\nif __name__ == \"__main__\":\n asyncio.run(main())\n```\n\n#### 参数说明\n\n| 参数名 | 类型 | 必填 | 默认值 | 说明 |\n|--------|------|------|--------|------|\n| url | str | 是 | - | 目标 URL |\n| output_format | Literal[\"json\", \"markdown\", \"csv\", \"screenshot\", \"toon\"] | 否 | markdown | 输出格式 |\n| schema | dict \\| None | 条件必填 | None | JSON Schema（当 output_format 为 \"json\" 时必填） |\n| render_javascript | bool | 否 | False | 是否渲染 JavaScript |\n| geo_location | str | 否 | None | 代理位置（ISO2 格式） |\n\n#### 返回数据模型\n\n```python\nclass AiScraperJob(BaseModel):\n run_id: str\n message: str | None = None\n data: str | dict | None\n```\n\n- 当 output_format 为 \"json\" 时，data 为字典\n- 当 output_format 为 \"markdown\" 时，data 为字符串\n- 当 output_format 为 \"csv\" 时，data 为 CSV 格式字符串\n- 当 output_format 为 \"screenshot\" 时，data 为字符串\n\n资料来源：[agentic_code_guide.md](https://github.com/oxylabs/oxylabs-ai-studio-py/blob/main/agentic_code_guide.md)\n\n### AI-Crawler（智能网站爬取）\n\n用于从起始 URL 开始爬取整个网站，根据自然语言提示引导提取过程。资料来源：[readme.md](https://github.com/oxylabs/oxylabs-ai-studio-py/blob/main/readme.md)\n\n#### 基本示例\n\n```python\nfrom oxylabs_ai_studio.apps.ai_crawler import AiCrawler\n\ncrawler = AiCrawler(api_key=\"\")\n\nurl = \"https://oxylabs.io\"\nresult = crawler.crawl(\n url=url,\n user_prompt=\"Find all pages with proxy products pricing\",\n output_format=\"markdown\",\n render_javascript=False,\n return_sources_limit=3,\n geo_location=\"France\",\n)\nprint(\"Results:\")\nfor item in result.data:\n print(item, \"\\n\")\n```\n\n资料来源：[examples/crawl_markdown.py](https://github.com/oxylabs/oxylabs-ai-studio-py/blob/main/examples/crawl_markdown.py)\n\n#### 使用 Pydantic Schema\n\n```python\nfrom pydantic import BaseModel, Field\nfrom oxylabs_ai_studio.apps.ai_crawler import AiCrawler\n\ncrawler = AiCrawler(api_key=\"\")\n\nclass ProxyPlan(BaseModel):\n name: str = Field(description=\"The name of the proxy plan\")\n price: str = Field(description=\"The price of the proxy plan\")\n features: list[str] = Field(description=\"The features of the proxy plan\")\n\nclass ProxyPlans(BaseModel):\n proxy_plans: list[ProxyPlan] = Field(description=\"The proxy plans\")\n\nurl = \"https://oxylabs.io/\"\nresult = crawler.crawl(\n url=url,\n user_prompt=\"Find all pages with proxy products pricing\",\n output_format=\"json\",\n schema=ProxyPlans.model_json_schema(),\n render_javascript=False,\n)\n```\n\n资料来源：[examples/crawl_pydantic_schema.py](https://github.com/oxylabs/oxylabs-ai-studio-py/blob/main/examples/crawl_pydantic_schema.py)\n\n#### 参数说明\n\n| 参数名 | 类型 | 必填 | 默认值 | 说明 |\n|--------|------|------|--------|------|\n| url | str | 是 | - | 起始 URL |\n| user_prompt | str | 是 | - | 自然语言提示 |\n| output_format | Literal[\"json\", \"markdown\", \"csv\", \"toon\"] | 否 | markdown | 输出格式 |\n| schema | dict \\| None | 条件必填 | None | JSON Schema（当 output_format 为 \"json\" 时必填） |\n| render_javascript | bool | 否 | False | 是否渲染 JavaScript |\n| return_sources_limit | int | 否 | 25 | 最大返回来源数量 |\n| geo_location | str | 否 | None | 代理位置 |\n| max_credits | int \\| None | 否 | None | 最大使用积分 |\n\n### AI-Search（SERP 搜索）\n\n用于执行搜索引擎结果页面（SERP）搜索。资料来源：[readme.md](https://github.com/oxylabs/oxylabs-ai-studio-py/blob/main/readme.md)\n\n#### 搜索并返回内容\n\n```python\nfrom oxylabs_ai_studio.apps.ai_search import AiSearch\n\nsearch = AiSearch(api_key=\"\")\n\nquery = \"lasagna recipe\"\nresult = search.search(\n query=query,\n limit=5,\n render_javascript=False,\n return_content=True,\n)\nprint(result.data)\n```\n\n资料来源：[examples/search_with_content.py](https://github.com/oxylabs/oxylabs-ai-studio-py/blob/main/examples/search_with_content.py)\n\n#### 即时搜索（快速）\n\n当 `limit <= 10` 且 `return_content=False` 时，搜索自动使用即时端点（`/search/instant`），返回结果更快。资料来源：[readme.md](https://github.com/oxylabs/oxylabs-ai-studio-py/blob/main/readme.md)\n\n```python\nfrom oxylabs_ai_studio.apps.ai_search import AiSearch\n\nsearch = AiSearch(api_key=\"\")\n\nquery = \"lasagna recipes\"\nresult = search.instant_search(\n query=query,\n limit=5,\n geo_location=\"United States\",\n)\nprint(result.data)\n```\n\n资料来源：[examples/search_instant.py](https://github.com/oxylabs/oxylabs-ai-studio-py/blob/main/examples/search_instant.py)\n\n#### 参数说明\n\n| 参数名 | 类型 | 必填 | 默认值 | 说明 |\n|--------|------|------|--------|------|\n| query | str | 是 | - | 搜索关键词 |\n| limit | int | 否 | 10 | 最大返回结果数（最大 50） |\n| render_javascript | bool | 否 | False | 是否渲染 JavaScript |\n| return_content | bool | 否 | True | 是否返回 Markdown 内容 |\n| geo_location | str | 否 | None | 地理位置（ISO2 格式或国家名） |\n\n### Browser-Agent（浏览器自动化）\n\n用于控制浏览器执行点击、滚动和导航等操作，根据文本提示执行动作。资料来源：[agentic_code_guide.md](https://github.com/oxylabs/oxylabs-ai-studio-py/blob/main/agentic_code_guide.md)\n\n#### 同步接口\n\n```python\nfrom oxylabs_ai_studio.apps.browser_agent import BrowserAgent\n\nbrowser_agent = BrowserAgent(api_key=\"\")\n\nprompt = \"Find if there is game 'super mario odyssey' in the store.\"\nurl = \"https://sandbox.oxylabs.io/\"\nresult = browser_agent.run(\n url=url,\n user_prompt=prompt,\n output_format=\"json\",\n schema={\"type\": \"object\", \"properties\": {\"page_url\": {\"type\": \"string\"}}, \"required\": []},\n)\nprint(result.data)\n```\n\n#### 异步接口\n\n```python\nimport asyncio\nfrom oxylabs_ai_studio.apps.browser_agent import BrowserAgent\n\nbrowser_agent = BrowserAgent(api_key=\"\")\n\nasync def main():\n prompt = \"Find if there is game 'super mario odyssey' in the store.\"\n url = \"https://sandbox.oxylabs.io/\"\n result = await browser_agent.run_async(\n url=url,\n user_prompt=prompt,\n output_format=\"json\",\n schema={\"type\": \"object\", \"properties\": {\"page_url\": {\"type\": \"string\"}}, \"required\": []},\n )\n print(result.data)\n\nif __name__ == \"__main__\":\n asyncio.run(main())\n```\n\n## Schema 生成\n\nSDK 提供了 `generate_schema` 方法，可以根据自然语言描述自动生成 JSON Schema，无需手动编写。资料来源：[examples/scrape_generated_schema.py](https://github.com/oxylabs/oxylabs-ai-studio-py/blob/main/examples/scrape_generated_schema.py)\n\n```python\nschema = scraper.generate_schema(\n prompt=\"want to parse developer, platform, type, price game title, genre (array) and description\"\n)\nprint(f\"Generated schema: {schema}\")\n```\n\n## 实现最佳实践\n\n根据官方指南，使用 SDK 时应遵循以下最佳实践：资料来源：[agentic_code_guide.md](https://github.com/oxylabs/oxylabs-ai-studio-py/blob/main/agentic_code_guide.md)\n\n1. **安装最新版本**：确保使用最新版本的 oxylabs-ai-studio\n2. **限流控制**：实现限流机制，遵守所购买套餐的速率限制\n3. **重试机制**：为处理失败的请求引入重试逻辑，但需设置重试次数上限以避免无限循环\n\n## 工作流程图\n\n```mermaid\ngraph TD\n A[安装 SDK] --> B[获取 API Key]\n B --> C[实例化应用类]\n C --> D{选择功能}\n D --> E[AiScraper]\n D --> F[AiCrawler]\n D --> G[AiSearch]\n D --> H[BrowserAgent]\n E --> I[调用 scrape 方法]\n F --> J[调用 crawl 方法]\n G --> K[调用 search/instant_search]\n H --> L[调用 run 方法]\n I --> M[处理返回结果]\n J --> M\n K --> M\n L --> M\n```\n\n## 常见输出格式对比\n\n| 输出格式 | 说明 | 返回类型 | 适用场景 |\n|----------|------|----------|----------|\n| markdown | Markdown 格式文本 | str | 内容展示、文档生成 |\n| json | 结构化 JSON | dict | 程序化处理、API 集成 |\n| csv | CSV 格式表格数据 | str | 数据分析、表格导出 |\n| screenshot | 页面截图 | str | 可视化存档、UI 验证 |\n| toon | 卡通化输出 | str | 特殊可视化需求 |\n\n## 异步编程支持\n\nSDK 同时支持同步和异步接口，便于集成到异步应用中：\n\n```python\nimport asyncio\nfrom oxylabs_ai_studio.apps.ai_scraper import AiScraper\n\nasync def main():\n scraper = AiScraper(api_key=\"\")\n result = await scraper.scrape_async(url=\"https://example.com\")\n print(result)\n\nasyncio.run(main())\n\n---\n\n\n\n## AI-Scraper 文档\n\n### 相关页面\n\n相关主题：[AI-Crawler 文档](#ai-crawler), [Schema 生成指南](#schema-generation), [API 客户端架构](#api-client)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [src/oxylabs_ai_studio/apps/ai_scraper.py](https://github.com/oxylabs/oxylabs-ai-studio-py/blob/main/src/oxylabs_ai_studio/apps/ai_scraper.py)\n- [examples/scrape_markdown.py](https://github.com/oxylabs/oxylabs-ai-studio-py/blob/main/examples/scrape_markdown.py)\n- [examples/scrape_pydantic_schema.py](https://github.com/oxylabs/oxylabs-ai-studio-py/blob/main/examples/scrape_pydantic_schema.py)\n- [examples/scrape_generated_schema.py](https://github.com/oxylabs/oxylabs-ai-studio-py/blob/main/examples/scrape_generated_schema.py)\n- [readme.md](https://github.com/oxylabs/oxylabs-ai-studio-py/blob/main/readme.md)\n- [agentic_code_guide.md](https://github.com/oxylabs/oxylabs-ai-studio-py/blob/main/agentic_code_guide.md)\n \n\n# AI-Scraper 文档\n\n## 概述\n\nAI-Scraper 是 Oxylabs AI Studio Python SDK 中的核心模块之一，专门用于从目标网页提取结构化或非结构化内容。该工具通过自然语言提示和 JSON Schema 定义，实现智能化的网页数据抓取功能，支持将网页内容转换为 Markdown、JSON、CSV 或截图格式。 资料来源：[readme.md](https://github.com/oxylabs/oxylabs-ai-studio-py/blob/main/readme.md)\n\nAI-Scraper 的主要应用场景包括：\n\n- **电商产品数据提取**：从商品页面抓取价格、描述、规格等信息\n- **内容聚合**：批量提取新闻、文章、评论等内容\n- **数据监控**：定期抓取网站内容进行市场分析\n- **结构化数据导出**：将网页数据转换为可读的 JSON 或 CSV 格式\n\n## 工作流程\n\n```mermaid\ngraph TD\n A[初始化 AiScraper] --> B[设置目标 URL]\n B --> C[定义输出格式]\n C --> D{output_format == json?}\n D -->|是| E[提供 JSON Schema]\n D -->|否| F[直接抓取]\n E --> G[调用 scrape 方法]\n F --> G\n G --> H[AI 引擎解析内容]\n H --> I[返回 AiScraperJob 结果]\n I --> J{data 类型}\n J -->|JSON| K[dict 对象]\n J -->|Markdown| L[字符串]\n J -->|CSV| M[CSV 格式字符串]\n J -->|Screenshot| N[图片字符串]\n```\n\n## 核心类定义\n\n### AiScraper\n\n`AiScraper` 是 AI-Scraper 模块的主类，负责处理网页抓取请求。 资料来源：[agentic_code_guide.md](https://github.com/oxylabs/oxylabs-ai-studio-py/blob/main/agentic_code_guide.md)\n\n#### 初始化\n\n```python\nfrom oxylabs_ai_studio.apps.ai_scraper import AiScraper\n\nscraper = AiScraper(api_key=\"\")\n```\n\n构造函数参数：\n\n| 参数 | 类型 | 必填 | 说明 |\n|------|------|------|------|\n| `api_key` | str | 是 | Oxylabs API 密钥，用于身份验证 |\n\n### AiScraperJob\n\n抓取任务完成后返回的数据模型类。\n\n```python\nclass AiScraperJob(BaseModel):\n run_id: str\n message: str | None = None\n data: str | dict | None\n```\n\n| 字段 | 类型 | 说明 |\n|------|------|------|\n| `run_id` | str | 任务唯一标识符 |\n| `message` | str \\| None | 任务状态消息或错误信息 |\n| `data` | str \\| dict \\| None | 返回的数据内容，类型取决于 output_format |\n\n资料来源：[agentic_code_guide.md](https://github.com/oxylabs/oxylabs-ai-studio-py/blob/main/agentic_code_guide.md)\n\n## API 方法\n\n### 同步接口\n\n`scrape` 方法用于执行同步网页抓取操作。\n\n```python\nfrom oxylabs_ai_studio.apps.ai_scraper import AiScraper\n\nscraper = AiScraper(api_key=\"\")\n\nurl = \"https://sandbox.oxylabs.io/products/3\"\nresult = scraper.scrape(\n url=url,\n output_format=\"json\",\n schema={\"type\": \"object\", \"properties\": {\"price\": {\"type\": \"string\"}}, \"required\": []},\n render_javascript=False,\n)\nprint(result)\n```\n\n资料来源：[agentic_code_guide.md](https://github.com/oxylabs/oxylabs-ai-studio-py/blob/main/agentic_code_guide.md)\n\n### 异步接口\n\n`scrape_async` 方法用于执行异步网页抓取操作，适用于需要并发处理多个请求的场景。\n\n```python\nimport asyncio\nfrom oxylabs_ai_studio.apps.ai_scraper import AiScraper\n\nscraper = AiScraper(api_key=\"\")\n\nasync def main():\n url = \"https://sandbox.oxylabs.io/products/3\"\n result = await scraper.scrape_async(\n url=url,\n output_format=\"json\",\n schema={\"type\": \"object\", \"properties\": {\"price\": {\"type\": \"string\"}}, \"required\": []},\n render_javascript=False,\n )\n print(result)\n\nif __name__ == \"__main__\":\n asyncio.run(main())\n```\n\n资料来源：[agentic_code_guide.md](https://github.com/oxylabs/oxylabs-ai-studio-py/blob/main/agentic_code_guide.md)\n\n### Schema 生成方法\n\n`generate_schema` 方法可以根据自然语言描述自动生成 JSON Schema，无需手动编写复杂的 Schema 定义。\n\n```python\nfrom oxylabs_ai_studio.apps.ai_scraper import AiScraper\n\nscraper = AiScraper(api_key=\"\")\n\nschema = scraper.generate_schema(\n prompt=\"want to parse developer, platform, type, price game title, genre (array) and description\"\n)\nprint(f\"Generated schema: {schema}\")\n```\n\n资料来源：[examples/scrape_generated_schema.py](https://github.com/oxylabs/oxylabs-ai-studio-py/blob/main/examples/scrape_generated_schema.py)\n\n## 参数说明\n\n### scrape / scrape_async 方法参数\n\n| 参数 | 类型 | 必填 | 默认值 | 说明 |\n|------|------|------|--------|------|\n| `url` | str | 是 | - | 目标网页 URL |\n| `output_format` | Literal[\"json\", \"markdown\", \"csv\", \"screenshot\", \"toon\"] | 否 | \"markdown\" | 输出格式类型 |\n| `schema` | dict \\| None | 条件必填 | None | JSON Schema，当 output_format 为 \"json\"、\"csv\" 或 \"toon\" 时必须提供 |\n| `render_javascript` | bool \\| string | 否 | False | 是否渲染 JavaScript，可设为 \"auto\" 自动检测 |\n| `geo_location` | str | 否 | - | 代理位置，使用 ISO2 格式或国家名称 |\n| `user_agent` | str | 否 | - | 自定义 User-Agent 请求头 |\n| `max_credits` | int \\| None | 否 | - | 最大使用的积分数量 |\n\n### output_format 可选值\n\n| 格式 | 说明 | schema 要求 |\n|------|------|-------------|\n| `markdown` | 返回 Markdown 格式的网页内容 | 不需要 |\n| `json` | 返回结构化 JSON 数据 | 必须提供 |\n| `csv` | 返回 CSV 格式数据 | 必须提供 |\n| `screenshot` | 返回网页截图（Base64 编码） | 不需要 |\n| `toon` | 返回卡通化数据表示 | 必须提供 |\n| `html` | 返回原始 HTML 内容 | 不需要 |\n\n资料来源：[readme.md](https://github.com/oxylabs/oxylabs-ai-studio-py/blob/main/readme.md)\n\n## 使用示例\n\n### 基础 Markdown 抓取\n\n抓取网页并以 Markdown 格式返回内容：\n\n```python\nfrom oxylabs_ai_studio.apps.ai_scraper import AiScraper\n\nscraper = AiScraper(api_key=\"\")\n\nurl = \"https://sandbox.oxylabs.io/products/1\"\nresult = scraper.scrape(\n url=url,\n output_format=\"markdown\",\n render_javascript=False,\n geo_location=\"Germany\",\n)\nprint(result)\n```\n\n资料来源：[examples/scrape_markdown.py](https://github.com/oxylabs/oxylabs-ai-studio-py/blob/main/examples/scrape_markdown.py)\n\n### 使用 JSON Schema 抓取结构化数据\n\n定义明确的 JSON Schema 来提取特定字段：\n\n```python\nfrom oxylabs_ai_studio.apps.ai_scraper import AiScraper\n\nscraper = AiScraper(api_key=\"\")\n\nurl = \"https://sandbox.oxylabs.io/products/3\"\nresult = scraper.scrape(\n url=url,\n output_format=\"json\",\n schema={\n \"type\": \"object\",\n \"properties\": {\n \"price\": {\"type\": \"string\"},\n \"title\": {\"type\": \"string\"}\n },\n \"required\": []\n },\n render_javascript=False,\n)\nprint(result.data)\n```\n\n资料来源：[agentic_code_guide.md](https://github.com/oxylabs/oxylabs-ai-studio-py/blob/main/agentic_code_guide.md)\n\n### 使用 Pydantic 模型\n\n通过 Pydantic 模型定义数据结构，利用 `model_json_schema()` 方法自动生成 Schema：\n\n```python\nfrom pydantic import BaseModel\nfrom oxylabs_ai_studio.apps.ai_scraper import AiScraper\n\nscraper = AiScraper(api_key=\"\")\n\nclass Game(BaseModel):\n title: str\n genre: list[str]\n developer: str\n platform: str\n game_type: str\n description: str\n price: str\n availability: str\n\nurl = \"https://sandbox.oxylabs.io/products/1\"\nresult = scraper.scrape(\n url=url,\n output_format=\"json\",\n schema=Game.model_json_schema(),\n render_javascript=False,\n)\nprint(result)\n```\n\n资料来源：[examples/scrape_pydantic_schema.py](https://github.com/oxylabs/oxylabs-ai-studio-py/blob/main/examples/scrape_pydantic_schema.py)\n\n### 使用自动生成的 Schema\n\n让 AI 自动根据描述生成 Schema，简化开发流程：\n\n```python\nfrom oxylabs_ai_studio.apps.ai_scraper import AiScraper\n\nscraper = AiScraper(api_key=\"\")\n\n# 自动生成 Schema\nschema = scraper.generate_schema(\n prompt=\"want to parse developer, platform, type, price game title, genre (array) and description\"\n)\nprint(f\"Generated schema: {schema}\")\n\n# 使用生成的 Schema 进行抓取\nurl = \"https://sandbox.oxylabs.io/products/3\"\nresult = scraper.scrape(\n url=url,\n output_format=\"json\",\n schema=schema,\n render_javascript=False,\n)\nprint(result)\n```\n\n资料来源：[examples/scrape_generated_schema.py](https://github.com/oxylabs/oxylabs-ai-studio-py/blob/main/examples/scrape_generated_schema.py)\n\n## JavaScript 渲染配置\n\n`render_javascript` 参数控制是否执行页面中的 JavaScript 代码：\n\n| 值 | 说明 |\n|----|------|\n| `False` | 不渲染 JavaScript（默认） |\n| `True` | 强制渲染 JavaScript |\n| `\"auto\"` | 自动检测是否需要渲染 |\n\n当设置为 `\"auto\"` 时，服务会自动判断目标网页是否需要 JavaScript 渲染才能完整显示内容。 资料来源：[readme.md](https://github.com/oxylabs/oxylabs-ai-studio-py/blob/main/readme.md)\n\n## 地理位置定位\n\n通过 `geo_location` 参数可以指定代理服务器的位置，以获取特定地区的内容版本：\n\n```python\nresult = scraper.scrape(\n url=url,\n output_format=\"markdown\",\n geo_location=\"Germany\", # 使用德国代理\n)\n```\n\n支持的格式：\n- ISO 2 字母代码（如 `\"DE\"`、`\"US\"`）\n- 国家标准名称（如 `\"Germany\"`、`\"United States\"`）\n\n资料来源：[readme.md](https://github.com/oxylabs/oxylabs-ai-studio-py/blob/main/readme.md)\n\n## 最佳实践\n\n### 速率限制\n\n确保实现遵守与购买计划关联的速率限制，以防止服务中断或过度使用。\n\n### 重试机制\n\n引入重试逻辑以处理失败的请求，但应设置重试次数上限，避免无限循环或过度 API 调用。\n\n### Schema 设计建议\n\n- 使用 Pydantic 模型定义复杂数据结构，便于类型检查和维护\n- 对于简单提取任务，使用 `generate_schema` 方法自动生成 Schema\n- 在 Schema 的 `required` 数组中仅包含必需字段，减少解析失败的概率\n\n### JavaScript 渲染策略\n\n- 仅在必要时启用 JavaScript 渲染，以优化性能和成本\n- 使用 `\"auto\"` 模式让系统自动决策\n- 对于纯静态页面，禁用渲染以提高响应速度\n\n## 返回值处理\n\n根据不同的 `output_format`，`result.data` 的类型会有所不同：\n\n| output_format | data 类型 | 示例 |\n|---------------|-----------|------|\n| `json` | dict | `{\"price\": \"$29.99\", \"title\": \"Product Name\"}` |\n| `markdown` | str | `\"# Product Title\\n\\nDescription...\"` |\n| `csv` | str | `\"name,price\\nItem 1,$10\"` |\n| `screenshot` | str | `\"data:image/png;base64,...\"` |\n\n访问返回数据：\n\n```python\nresult = scraper.scrape(url=url, output_format=\"json\", schema=schema)\nif isinstance(result.data, dict):\n price = result.data.get(\"price\")\n print(f\"价格: {price}\")\n```\n\n资料来源：[agentic_code_guide.md](https://github.com/oxylabs/oxylabs-ai-studio-py/blob/main/agentic_code_guide.md)\n\n## 错误处理\n\n建议实现完整的错误处理机制：\n\n```python\nfrom oxylabs_ai_studio.apps.ai_scraper import AiScraper\nfrom oxylabs_ai_studio.exceptions import (\n AuthenticationError,\n RateLimitError,\n ScrapingError\n)\n\nscraper = AiScraper(api_key=\"\")\n\ntry:\n result = scraper.scrape(\n url=url,\n output_format=\"markdown\",\n )\n if result.message:\n print(f\"警告: {result.message}\")\n print(result.data)\nexcept AuthenticationError:\n print(\"API 密钥无效\")\nexcept RateLimitError:\n print(\"速率限制已达到，请稍后重试\")\nexcept ScrapingError as e:\n print(f\"抓取失败: {e}\")\n\n---\n\n\n\n## AI-Crawler 文档\n\n### 相关页面\n\n相关主题：[AI-Scraper 文档](#ai-scraper), [AI-Map 文档](#ai-map), [Schema 生成指南](#schema-generation)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [src/oxylabs_ai_studio/apps/ai_crawler.py](https://github.com/oxylabs/oxylabs-ai-studio-py/blob/main/src/oxylabs_ai_studio/apps/ai_crawler.py)\n- [examples/crawl_markdown.py](https://github.com/oxylabs/oxylabs-ai-studio-py/blob/main/examples/crawl_markdown.py)\n- [examples/crawl_pydantic_schema.py](https://github.com/oxylabs/oxylabs-ai-studio-py/blob/main/examples/crawl_pydantic_schema.py)\n- [examples/crawl_generated_schema.py](https://github.com/oxylabs/oxylabs-ai-studio-py/blob/main/examples/crawl_generated_schema.py)\n \n\n# AI-Crawler 文档\n\n## 概述\n\nAI-Crawler 是 Oxylabs AI Studio Python SDK 中的核心模块之一，专门用于自动化网页爬取任务。该模块基于自然语言提示词驱动，能够智能识别和提取目标网页中的相关内容，支持多种输出格式和结构化数据提取。\n\nAI-Crawler 继承自 `OxyStudioAIClient` 基类，通过异步轮询机制与 Oxylabs 后端 API 进行交互，实现高效的网页内容抓取。资料来源：[src/oxylabs_ai_studio/apps/ai_crawler.py:35]()\n\n## 核心组件\n\n### 数据模型\n\nAI-Crawler 使用 Pydantic BaseModel 定义返回数据结构，确保类型安全和数据验证。\n\n```python\nclass AiCrawlerJob(BaseModel):\n run_id: str\n message: str | None = None\n data: list[dict[str, Any]] | list[str] | None = None\n```\n\n| 字段 | 类型 | 说明 |\n|------|------|------|\n| `run_id` | str | 爬取任务的唯一标识符 |\n| `message` | str \\| None | 任务执行过程中的消息或错误代码 |\n| `data` | list \\| None | 爬取结果数据，格式取决于 output_format 参数 |\n\n资料来源：[src/oxylabs_ai_studio/apps/ai_crawler.py:22-25]()\n\n### 配置常量\n\n| 常量 | 值 | 说明 |\n|------|-----|------|\n| `CRAWLER_TIMEOUT_SECONDS` | 600 (10分钟) | 爬取任务的最大超时时间 |\n| `POLL_INTERVAL_SECONDS` | 5 | 轮询后端状态的间隔时间（秒） |\n| `POLL_MAX_ATTEMPTS` | 120 | 最大轮询次数 |\n\n资料来源：[src/oxylabs_ai_studio/apps/ai_crawler.py:9-11]()\n\n## 主要功能\n\n### 1. 网页爬取 (crawl)\n\n`crawl()` 方法是 AiCrawler 的核心功能，用于执行网页爬取任务。\n\n```python\ndef crawl(\n self,\n url: str,\n user_prompt: str,\n output_format: Literal[\"json\", \"markdown\", \"csv\", \"toon\"] = \"markdown\",\n schema: dict[str, Any] | None = None,\n render_javascript: bool = False,\n return_sources_limit: int = 25,\n geo_location: str | None = None,\n max_credits: int | None = None,\n) -> AiCrawlerJob\n```\n\n#### 参数说明\n\n| 参数 | 类型 | 必需 | 默认值 | 说明 |\n|------|------|------|--------|------|\n| `url` | str | 是 | - | 爬取的起始 URL |\n| `user_prompt` | str | 是 | - | 自然语言提示词，指导提取内容 |\n| `output_format` | Literal | 否 | \"markdown\" | 输出格式 |\n| `schema` | dict | 条件必需 | None | JSON Schema，当 output_format 为 json/csv/toon 时必填 |\n| `render_javascript` | bool | 否 | False | 是否渲染 JavaScript |\n| `return_sources_limit` | int | 否 | 25 | 最大返回来源数量 |\n| `geo_location` | str | 否 | None | 代理位置（ISO2 格式或国家名称） |\n| `max_credits` | int | 否 | None | 最大使用积分限制 |\n\n资料来源：[src/oxylabs_ai_studio/apps/ai_crawler.py:32-41]()\n\n#### 业务逻辑验证\n\n当 `output_format` 设置为 `json`、`csv` 或 `toon` 时，必须提供 `schema` 参数，否则将抛出 `ValueError`：\n\n```python\nif output_format in [\"json\", \"csv\", \"toon\"] and schema is None:\n raise ValueError(\n \"openapi_schema is required when output_format is json, csv or toon.\",\n )\n```\n\n资料来源：[src/oxylabs_ai_studio/apps/ai_crawler.py:44-48]()\n\n### 2. Schema 生成 (generate_schema)\n\n`generate_schema()` 方法允许用户通过自然语言描述自动生成 JSON Schema，无需手动编写复杂的 Schema 定义。\n\n```python\ndef generate_schema(self, prompt: str) -> dict[str, Any] | None:\n logger.info(\"Generating schema\")\n body = {\"user_prompt\": prompt}\n response = self.call_api(\n client=self.get_client(),\n url=\"/crawl/generate-params\",\n method=\"POST\",\n body=body,\n )\n if response.status_code != 200:\n raise Exception(f\"Failed to generate schema: {response.text}\")\n json_response: SchemaResponse = response.json()\n return json_response.get(\"data\", {}).get(\"schema\")\n```\n\n资料来源：[src/oxylabs_ai_studio/apps/ai_crawler.py:68-80]()\n\n## 执行流程\n\nAI-Crawler 采用同步轮询机制获取爬取结果，其工作流程如下：\n\n```mermaid\ngraph TD\n A[开始 crawl 调用] --> B[调用 /crawl/run 接口提交任务]\n B --> C{响应状态码}\n C -->|202| D[提取 run_id]\n C -->|其他| E[抛出异常]\n D --> F[轮询 /crawl/run/data 接口]\n F --> G{获取状态}\n G -->|202 processing| F\n G -->|200 completed| H[返回 AiCrawlerJob]\n G -->|200 failed| I[返回 AiCrawlerJob with error]\n G -->|其他| F\n H --> J[结束]\n I --> J\n E --> J\n```\n\n### 超时处理\n\n当轮询次数超过 `POLL_MAX_ATTEMPTS`（120次）或总耗时超过 `CRAWLER_TIMEOUT_SECONDS`（600秒）时，任务将抛出 `TimeoutError`：\n\n```python\nraise TimeoutError(f\"Failed to crawl {url}: timeout.\")\n```\n\n资料来源：[src/oxylabs_ai_studio/apps/ai_crawler.py:61]()\n\n### 用户中断处理\n\n支持 `KeyboardInterrupt` 异常捕获，允许用户通过中断信号取消爬取任务：\n\n```python\nexcept KeyboardInterrupt:\n logger.info(\"[Cancelled] Crawling was cancelled by user.\")\n raise KeyboardInterrupt from None\n```\n\n资料来源：[src/oxylabs_ai_studio/apps/ai_crawler.py:57-59]()\n\n## 使用示例\n\n### 示例一：Markdown 格式输出\n\n```python\nfrom oxylabs_ai_studio.apps.ai_crawler import AiCrawler\n\ncrawler = AiCrawler(api_key=\"\")\n\nurl = \"https://oxylabs.io\"\nresult = crawler.crawl(\n url=url,\n user_prompt=\"Find all pages with proxy products pricing\",\n output_format=\"markdown\",\n render_javascript=False,\n return_sources_limit=3,\n geo_location=\"France\",\n)\nprint(\"Results:\")\nfor item in result.data:\n print(item, \"\\n\")\n```\n\n资料来源：[examples/crawl_markdown.py]() 和 [readme.md]()\n\n### 示例二：使用 Pydantic Schema\n\n```python\nfrom pydantic import BaseModel, Field\nfrom oxylabs_ai_studio.apps.ai_crawler import AiCrawler\n\ncrawler = AiCrawler(api_key=\"\")\n\nclass ProxyPlan(BaseModel):\n name: str = Field(description=\"The name of the proxy plan\")\n price: str = Field(description=\"The price of the proxy plan\")\n features: list[str] = Field(description=\"The features of the proxy plan\")\n\nclass ProxyPlans(BaseModel):\n proxy_plans: list[ProxyPlan] = Field(description=\"The proxy plans\")\n\nurl = \"https://oxylabs.io/\"\nresult = crawler.crawl(\n url=url,\n user_prompt=\"Find all pages with proxy products pricing\",\n output_format=\"json\",\n schema=ProxyPlans.model_json_schema(),\n render_javascript=False,\n)\nprint(\"Results:\\n\")\nfor item in result.data:\n print(item, \"\\n\")\n```\n\n资料来源：[examples/crawl_pydantic_schema.py]()\n\n### 示例三：自动生成 Schema\n\n```python\nfrom oxylabs_ai_studio.apps.ai_crawler import AiCrawler\n\ncrawler = AiCrawler(api_key=\"\")\n\nschema = crawler.generate_schema(\n prompt=\"proxy plans which have name, price, and features\",\n)\nprint(\"schema: \", schema)\n\nurl = \"https://oxylabs.io\"\nresult = crawler.crawl(\n url=url,\n user_prompt=\"Find all pages with proxy products pricing\",\n output_format=\"json\",\n schema=schema,\n render_javascript=False,\n)\nprint(\"Results:\")\nfor item in result.data:\n print(item, \"\\n\")\n```\n\n资料来源：[examples/crawl_generated_schema.py]()\n\n## 输出格式\n\n| 格式 | 说明 | Schema 要求 |\n|------|------|-------------|\n| `markdown` | 返回 Markdown 格式的文本内容 | 不需要 |\n| `json` | 返回结构化 JSON 数据 | **必需** |\n| `csv` | 返回 CSV 格式的表格数据 | **必需** |\n| `toon` | 返回特定的数据格式 | **必需** |\n\n资料来源：[src/oxylabs_ai_studio/apps/ai_crawler.py:37]()\n\n## 地理位置支持\n\n`geo_location` 参数支持多种格式：\n\n- ISO 2 字母国家代码（如 `FR`、`DE`、`US`）\n- 国家正式名称（如 `France`、`Germany`、`United States`）\n\n支持的地理位置列表可参考 [官方文档](https://developers.oxylabs.io/scraping-solutions/web-scraper-api/features/localization/proxy-location#list-of-supported-geo_location-values)。\n\n资料来源：[readme.md]()\n\n## 错误处理\n\n### 常见错误场景\n\n| 场景 | 处理方式 |\n|------|----------|\n| Schema 缺失 | 抛出 `ValueError` |\n| API 请求失败 | 抛出 `Exception` |\n| 任务超时 | 抛出 `TimeoutError` |\n| 任务执行失败 | 返回 `AiCrawlerJob` 并包含 `message` 错误信息 |\n| 用户中断 | 抛出 `KeyboardInterrupt` |\n\n### 任务状态流转\n\n```mermaid\nstateDiagram-v2\n [*] --> Processing: 任务提交\n Processing --> Processing: 状态码 202\n Processing --> Completed: 状态码 200 + status=\"completed\"\n Processing --> Failed: 状态码 200 + status=\"failed\"\n Completed --> [*]\n Failed --> [*]\n```\n\n## 最佳实践\n\n### 1. 合理设置超时时间\n\n默认超时时间为 10 分钟，适用于大多数爬取任务。对于大型网站或网络环境较差的情况，可考虑：\n\n- 使用 `render_javascript=True` 时预留更多时间\n- 分批次爬取以降低单次任务复杂度\n\n### 2. Schema 设计建议\n\n- 使用清晰的字段描述（description）\n- 对于数组类型，指定 `items` 的具体结构\n- 使用 Pydantic 模型时，通过 `model_json_schema()` 方法自动转换\n\n### 3. 积分控制\n\n通过 `max_credits` 参数限制单次任务的最大积分消耗，避免意外超额：\n\n```python\nresult = crawler.crawl(\n url=url,\n user_prompt=\"Find all pages with proxy products pricing\",\n max_credits=100,\n)\n```\n\n### 4. 地理位置选择\n\n选择与目标网站服务器相近的地理位置可提高响应速度和稳定性：\n\n```python\ngeo_location=\"Germany\" # 爬取德国服务器网站时推荐\n```\n\n## 类层次结构\n\n```\nOxyStudioAIClient (基类)\n └── AiCrawler (子类)\n```\n\n| 类名 | 继承关系 | 主要职责 |\n|------|----------|----------|\n| `OxyStudioAIClient` | - | HTTP 客户端封装、API 认证 |\n| `AiCrawler` | 继承 OxyStudioAIClient | 爬取业务逻辑实现 |\n\n资料来源：[src/oxylabs_ai_studio/apps/ai_crawler.py:35]()\n\n## 依赖模块\n\n| 模块 | 来源 | 用途 |\n|------|------|------|\n| `asyncio` | Python 标准库 | 异步支持（预留） |\n| `time` | Python 标准库 | 轮询延迟控制 |\n| `typing` | Python 标准库 | 类型注解 |\n| `pydantic` | 外部依赖 | 数据模型验证 |\n| `oxylabs_ai_studio.client` | 本地模块 | HTTP 客户端基类 |\n| `oxylabs_ai_studio.logger` | 本地模块 | 日志记录 |\n| `oxylabs_ai_studio.models` | 本地模块 | 数据模型定义 |\n\n资料来源：[src/oxylabs_ai_studio/apps/ai_crawler.py:1-8]()\n\n## 总结\n\nAI-Crawler 模块提供了一套完整的智能网页爬取解决方案，其核心优势包括：\n\n- **自然语言驱动**：通过 `user_prompt` 描述提取需求，无需编写复杂的 CSS/XPath 选择器\n- **多格式支持**：原生支持 Markdown、JSON、CSV 等多种输出格式\n- **Schema 自动生成**：降低结构化数据提取的学习成本\n- **完善的错误处理**：统一的异常处理机制和任务状态追踪\n- **灵活的地理定位**：支持全球多地区的代理爬取\n\n开发者可通过本模块快速实现复杂网页内容的结构化提取，适用于价格监控、竞品分析、内容聚合等多种应用场景。\n\n---\n\n\n\n## AI-Search 文档\n\n### 相关页面\n\n相关主题：[AI-Scraper 文档](#ai-scraper), [AI-Map 文档](#ai-map)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [src/oxylabs_ai_studio/apps/ai_search.py](https://github.com/oxylabs/oxylabs-ai-studio-py/blob/main/src/oxylabs_ai_studio/apps/ai_search.py)\n- [examples/search_with_content.py](https://github.com/oxylabs/oxylabs-ai-studio-py/blob/main/examples/search_with_content.py)\n- [examples/search_no_content.py](https://github.com/oxylabs/oxylabs-ai-studio-py/blob/main/examples/search_no_content.py)\n- [examples/search_instant.py](https://github.com/oxylabs/oxylabs-ai-studio-py/blob/main/examples/search_instant.py)\n \n\n# AI-Search 文档\n\n## 概述\n\nAI-Search 是 Oxylabs AI Studio Python SDK 中的搜索引擎模块，提供基于自然语言处理的智能搜索功能。该模块封装了与 Oxylabs AI Search API 的交互逻辑，支持同步和异步两种调用方式，能够执行标准搜索和即时搜索两种模式。\n\n主要功能包括：\n\n- 执行 SERP（搜索引擎结果页面）搜索\n- 支持返回完整的 Markdown 内容\n- 提供即时搜索模式（适用于少量结果场景）\n- 支持地理位置定位\n- 支持 JavaScript 渲染\n\n## 核心类与数据模型\n\n### AiSearchJob 类\n\n`AiSearchJob` 是搜索任务的返回结果模型，继承自 Pydantic 的 `BaseModel`：\n\n| 字段 | 类型 | 描述 |\n|------|------|------|\n| `run_id` | `str` | 搜索任务的唯一标识符 |\n| `message` | `str \\| None` | 状态消息或错误代码 |\n| `data` | `list[SearchResult] \\| None` | 搜索结果数据列表 |\n\n资料来源：[src/oxylabs_ai_studio/apps/ai_search.py:21-23]()\n\n### SearchResult 类\n\n`SearchResult` 定义了单条搜索结果的数据结构：\n\n| 字段 | 类型 | 描述 |\n|------|------|------|\n| `url` | `str` | 搜索结果的网页地址 |\n| `title` | `str` | 搜索结果的标题 |\n| `description` | `str` | 搜索结果的描述/摘要 |\n| `content` | `str \\| None` | 可选的 Markdown 格式内容 |\n\n资料来源：[src/oxylabs_ai_studio/apps/ai_search.py:14-18]()\n\n## AiSearch 类\n\n`AiSearch` 类是搜索引擎模块的主入口类，继承自 `OxyStudioAIClient` 基类：\n\n```python\nclass AiSearch(OxyStudioAIClient):\n \"\"\"AI Search app.\"\"\"\n\n def __init__(self, api_key: str | None = None):\n super().__init__(api_key=api_key)\n```\n\n资料来源：[src/oxylabs_ai_studio/apps/ai_search.py:26-29]()\n\n## 架构与工作流程\n\n### 搜索流程图\n\n```mermaid\ngraph TD\n A[开始搜索] --> B{limit <= 10 且 return_content = False?}\n B -->|是| C[调用 instant_search 即时搜索]\n B -->|否| D[调用 /search/run 创建任务]\n C --> E[直接返回结果]\n D --> F{轮询状态}\n F -->|202 状态码| G[等待 POLL_INTERVAL_SECONDS]\n G --> F\n F -->|200 完成| H[返回 AiSearchJob]\n F -->|失败| I[返回失败状态]\n E --> J[结束]\n H --> J\n I --> J\n```\n\n### 轮询机制参数\n\n| 参数 | 值 | 描述 |\n|------|-----|------|\n| `SEARCH_TIMEOUT_SECONDS` | 180 秒 (3分钟) | 搜索超时时间 |\n| `POLL_INTERVAL_SECONDS` | 5 秒 | 轮询间隔时间 |\n| `POLL_MAX_ATTEMPTS` | 36 | 最大轮询次数 |\n\n资料来源：[src/oxylabs_ai_studio/apps/ai_search.py:9-11]()\n\n## 同步接口\n\n### 标准搜索 (search 方法)\n\n标准搜索采用轮询机制，适用于需要获取完整内容的场景：\n\n```python\nfrom oxylabs_ai_studio.apps.ai_search import AiSearch\n\nsearch = AiSearch(api_key=\"\")\n\nquery = \"lasagna recipe\"\nresult = search.search(\n query=query,\n limit=5,\n render_javascript=False,\n return_content=True,\n)\nprint(result.data)\n```\n\n资料来源：[examples/search_with_content.py:1-13]()\n\n### 搜索不带内容 (return_content=False)\n\n当不需要返回完整内容时，可以设置 `return_content=False`：\n\n```python\nfrom oxylabs_ai_studio.apps.ai_search import AiSearch\n\nsearch = AiSearch(api_key=\"\")\n\nquery = \"lasagna\"\nresult = search.search(\n query=query,\n limit=5,\n render_javascript=False,\n return_content=False,\n geo_location=\"Italy\",\n)\nprint(result.data)\n```\n\n资料来源：[examples/search_no_content.py:1-15]()\n\n## 即时搜索 (instant_search 方法)\n\n即时搜索是一种快速搜索模式，适用于以下条件：\n\n- `limit <= 10`\n- `return_content = False`\n\n即时搜索直接调用 `/search/instant` 端点，无需轮询，立即返回结果。\n\n```python\nfrom oxylabs_ai_studio.apps.ai_search import AiSearch\n\nsearch = AiSearch(api_key=\"\")\n\nquery = \"lasagna recipes\"\nresult = search.instant_search(\n query=query,\n limit=5,\n geo_location=\"United States\",\n)\nprint(result.data)\n```\n\n资料来源：[examples/search_instant.py:1-13]()\n\n## 异步接口\n\n### 异步搜索 (search_async 方法)\n\n异步版本的搜索方法，适用于异步应用程序：\n\n```python\nimport asyncio\nfrom oxylabs_ai_studio.apps.ai_search import AiSearch\n\nsearch = AiSearch(api_key=\"\")\n\nasync def main():\n result = await search.search_async(\n query=\"lasagna recipe\",\n limit=5,\n render_javascript=False,\n return_content=True,\n )\n print(result.data)\n\nif __name__ == \"__main__\":\n asyncio.run(main())\n```\n\n异步接口的内部逻辑与同步版本相同，首先判断是否满足即时搜索条件，满足则调用 `instant_search_async` 方法。\n\n资料来源：[src/oxylabs_ai_studio/apps/ai_search.py:57-106]()\n\n### 异步即时搜索 (instant_search_async 方法)\n\n异步即时搜索方法：\n\n```python\nasync def instant_search_async(\n self,\n query: str,\n limit: int = 10,\n geo_location: str | None = None,\n) -> AiSearchJob:\n \"\"\"Async instant SERP search.\"\"\"\n if not query:\n raise ValueError(\"query is required\")\n body = {\n \"query\": query,\n \"limit\": limit,\n \"geo_location\": geo_location,\n }\n async with self.async_client() as client:\n response = await self.call_api_async(\n client=client, url=\"/search/instant\", method=\"POST\", body=body\n )\n status_code = response.status_code\n if status_code != 200:\n raise Exception(f\"Failed to perform instant search: `{response.text}`\")\n resp_body = response.json()\n return AiSearchJob(\n run_id=resp_body.get(\"run_id\", \"\"),\n message=resp_body.get(\"status\", None),\n data=resp_body.get(\"data\", None),\n )\n```\n\n资料来源：[src/oxylabs_ai_studio/apps/ai_search.py:153-175]()\n\n## 参数说明\n\n### search / search_async 方法参数\n\n| 参数 | 类型 | 默认值 | 必填 | 描述 |\n|------|------|--------|------|------|\n| `query` | `str` | - | **是** | 搜索查询关键词 |\n| `limit` | `int` | 10 | 否 | 最大返回结果数，最大值 50 |\n| `render_javascript` | `bool` | `False` | 否 | 是否渲染 JavaScript |\n| `return_content` | `bool` | `True` | 否 | 是否返回 Markdown 内容 |\n| `geo_location` | `str \\| None` | `None` | 否 | 地理位置，ISO2 格式或国家名称 |\n\n### instant_search / instant_search_async 方法参数\n\n| 参数 | 类型 | 默认值 | 必填 | 描述 |\n|------|------|--------|------|------|\n| `query` | `str` | - | **是** | 搜索查询关键词 |\n| `limit` | `int` | 10 | 否 | 最大返回结果数，最大 10 |\n| `geo_location` | `str \\| None` | `None` | 否 | 地理位置信息 |\n\n## 使用场景对比\n\n| 场景 | 推荐方法 | 原因 |\n|------|----------|------|\n| 快速预览搜索结果 | `instant_search` | 无需轮询，立即返回 |\n| 需要完整 Markdown 内容 | `search` (return_content=True) | 轮询获取完整内容 |\n| 批量搜索（结果较多） | `search` | 支持最多 50 条结果 |\n| 异步应用集成 | `search_async` / `instant_search_async` | 支持异步调用 |\n\n## 地理位置支持\n\n`geo_location` 参数支持多种格式：\n\n- ISO 2-letter 格式（如 \"US\", \"DE\"）\n- 国家规范名称（如 \"United States\", \"Germany\"）\n- 坐标格式（高级定位场景）\n\n地理位置功能允许搜索特定区域的内容，返回针对该地区的搜索引擎结果。\n\n## 错误处理\n\n### 常见错误\n\n| 错误类型 | 触发条件 | 处理方式 |\n|----------|----------|----------|\n| `ValueError` | query 参数为空 | 检查并提供有效的查询字符串 |\n| `TimeoutError` | 轮询超时（3分钟） | 增加超时时间或重试 |\n| `Exception` | API 返回非 200 状态码 | 检查 API 密钥和网络连接 |\n\n### 超时与重试机制\n\n```mermaid\ngraph LR\n A[发起请求] --> B{响应状态}\n B -->|200| C[返回成功结果]\n B -->|202| D[等待 5 秒]\n D --> B\n B -->|其他| E[等待 5 秒重试]\n E --> B\n C --> F[结束]\n G[超时 3 分钟] --> H[抛出 TimeoutError]\n```\n\n## 返回值示例\n\n### 成功响应 (AiSearchJob)\n\n```python\nAiSearchJob(\n run_id=\"abc123-def456\",\n message=None,\n data=[\n SearchResult(\n url=\"https://example.com/recipe/lasagna\",\n title=\"Classic Italian Lasagna Recipe\",\n description=\"A delicious traditional lasagna...\",\n content=\"# Lasagna Recipe\\n\\n## Ingredients\\n...\"\n ),\n SearchResult(\n url=\"https://example.com/lasagna-tips\",\n title=\"10 Tips for Perfect Lasagna\",\n description=\"Learn how to make...\",\n content=None\n )\n ]\n)\n```\n\n### 即时搜索响应\n\n即时搜索返回的数据结构相同，但不包含 `content` 字段：\n\n```python\nAiSearchJob(\n run_id=\"xyz789\",\n message=\"completed\",\n data=[\n SearchResult(\n url=\"https://example.com/recipe\",\n title=\"Recipe\",\n description=\"Description...\",\n content=None\n )\n ]\n)\n```\n\n## 最佳实践\n\n1. **选择合适的搜索方法**\n - 需要内容时使用 `search()` 并设置 `return_content=True`\n - 快速预览使用 `instant_search()`\n\n2. **合理设置 limit**\n - 即时搜索最大 10 条\n - 标准搜索最大 50 条\n\n3. **地理位置优化**\n - 根据目标受众设置正确的地理位置\n - 支持多语言内容定向\n\n4. **错误处理**\n - 实现重试机制应对临时网络问题\n - 设置合理的超时时间\n\n5. **异步应用**\n - 在异步环境中优先使用异步方法\n - 配合 asyncio 事件循环使用\n\n---\n\n\n\n## AI-Map 文档\n\n### 相关页面\n\n相关主题：[AI-Crawler 文档](#ai-crawler), [AI-Search 文档](#ai-search)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [src/oxylabs_ai_studio/apps/ai_map.py](https://github.com/oxylabs/oxylabs-ai-studio-py/blob/main/src/oxylabs_ai_studio/apps/ai_map.py)\n- [examples/ai_map.py](https://github.com/oxylabs/oxylabs-ai-studio-py/blob/main/examples/ai_map.py)\n- [readme.md](https://github.com/oxylabs/oxylabs-ai-studio-py/blob/main/readme.md)\n- [agentic_code_guide.md](https://github.com/oxylabs/oxylabs-ai-studio-py/blob/main/agentic_code_guide.md)\n \n\n# AI-Map 文档\n\n## 概述\n\nAI-Map 是 Oxylabs AI Studio SDK 中的站点地图映射模块，通过 AI 技术自动发现并映射网站结构。该模块能够根据指定的关键词或自然语言提示，在给定域名的不同路径层级中查找相关 URL，帮助用户快速建立目标站点的链接图谱。\n\nAI-Map 的核心价值在于将传统的被动 sitemap 解析与主动的智能发现相结合。它不仅能够读取标准的站点地图文件，还可以通过关键词匹配和 AI 驱动的路径预测，发现那些在 sitemap 中未被收录但实际存在的页面。\n\n## 核心功能\n\nAI-Map 模块提供以下主要能力：\n\n| 功能 | 说明 |\n|------|------|\n| 智能站点发现 | 基于关键词和自然语言提示发现相关页面 |\n| 多层级爬取 | 支持 1-5 层的深度爬取配置 |\n| 动态 sitemap | 可选择性集成现有 sitemap 作为种子 |\n| 地理定位 | 支持按国家/地区进行定向爬取 |\n| 域名控制 | 可限制爬取范围在子域名或主域名内 |\n\n## 快速开始\n\n### 基础调用示例\n\n```python\nfrom oxylabs_ai_studio.apps.ai_map import AiMap\n\nai_map = AiMap(api_key=\"\")\npayload = {\n \"url\": \"https://career.oxylabs.io\",\n \"search_keywords\": [\"career\", \"jobs\", \"vacancy\"],\n \"user_prompt\": \"job ad pages\",\n \"max_crawl_depth\": 2,\n \"limit\": 10,\n \"geo_location\": \"Germany\",\n \"render_javascript\": False,\n \"include_sitemap\": True,\n \"max_credits\": None,\n \"allow_subdomains\": False,\n \"allow_external_domains\": False,\n}\nresult = ai_map.map(**payload)\nprint(result.data)\n```\n\n资料来源：[readme.md](https://github.com/oxylabs/oxylabs-ai-studio-py/blob/main/readme.md)\n\n## 工作流程\n\n```mermaid\ngraph TD\n A[输入 URL 和配置] --> B[初始化爬取任务]\n B --> C{include_sitemap 配置}\n C -->|是| D[解析并加载 sitemap]\n C -->|否| E[跳过 sitemap]\n D --> F[生成初始 URL 队列]\n E --> F\n F --> G[按 max_crawl_depth 层级爬取]\n G --> H{search_keywords 过滤}\n H -->|匹配| I[URL 进入结果集]\n H -->|不匹配| J[丢弃]\n I --> K{limit 检查}\n K -->|未达上限| G\n K -->|已达上限| L[返回映射结果]\n J --> G\n```\n\n## 参数说明\n\n### 必需参数\n\n| 参数名 | 类型 | 说明 |\n|--------|------|------|\n| url | str | 起始 URL 或域名，用于开始映射任务 |\n\n### 可选参数\n\n| 参数名 | 类型 | 默认值 | 说明 |\n|--------|------|--------|------|\n| search_keywords | list[str] | None | 用于过滤 URL 路径的关键词列表 |\n| user_prompt | str \\| None | None | 自然语言提示，用于关键词搜索。可与 search_keywords 配合使用或单独使用 |\n| max_crawl_depth | int | 1 | 最大爬取深度，范围 1-5 |\n| limit | int | 25 | 返回的最大 URL 数量 |\n| geo_location | str | None | 代理位置，使用 ISO2 格式或国家标准名称 |\n| render_javascript | bool | False | 是否启用 JavaScript 渲染 |\n| include_sitemap | bool | True | 是否将 sitemap 作为种子来源 |\n| max_credits | int \\| None | None | 使用的最大积分额度 |\n| allow_subdomains | bool | False | 是否允许爬取子域名 |\n| allow_external_domains | bool | False | 是否允许爬取外部域名 |\n\n## 配置详解\n\n### 深度爬取策略\n\n`max_crawl_depth` 参数控制爬取遍历的层级深度。合理的深度设置对结果质量和资源消耗有显著影响：\n\n| 深度值 | 适用场景 | 预期 URL 数量 |\n|--------|----------|---------------|\n| 1 | 浅层页面发现 | 10-50 |\n| 2 | 一般网站结构探索 | 50-200 |\n| 3 | 中型网站完整映射 | 200-1000 |\n| 4-5 | 大型网站深层探索 | 1000+ |\n\n### 关键词过滤机制\n\n`search_keywords` 参数支持多关键词匹配，URL 路径中包含任一关键词的页面将被保留：\n\n```python\npayload = {\n \"url\": \"https://example.com\",\n \"search_keywords\": [\"product\", \"category\", \"search\"],\n # ...\n}\n```\n\n资料来源：[readme.md](https://github.com/oxylabs/oxylabs-ai-studio-py/blob/main/readme.md)\n\n### 域名访问控制\n\n通过 `allow_subdomains` 和 `allow_external_domains` 两个布尔参数，可以精确控制爬取范围：\n\n| allow_subdomains | allow_external_domains | 行为描述 |\n|------------------|------------------------|----------|\n| False | False | 仅爬取主域名，不含子域名和外部链接 |\n| True | False | 允许子域名，但不允许外部域名 |\n| False | True | 允许外部域名，但不允许子域名 |\n| True | True | 无限制，所有域名均可访问 |\n\n### Sitemap 集成\n\n`include_sitemap` 参数默认为 `True`，这意味着模块会自动尝试从 `域名/sitemap.xml` 获取已知的 URL 作为种子。如果网站没有 sitemap 文件或文件不完整，建议同时配置 `search_keywords` 以确保发现更多相关页面。\n\n## 返回结果\n\nAI-Map 的 `map()` 方法返回 `AiMapJob` 对象，包含以下属性：\n\n| 属性 | 类型 | 说明 |\n|------|------|------|\n| run_id | str | 任务唯一标识符 |\n| message | str \\| None | 状态消息或错误信息 |\n| data | dict \\| None | 映射结果数据 |\n\n访问结果数据的方式：\n\n```python\nresult = ai_map.map(**payload)\nprint(result.data)\n```\n\n## 使用场景\n\n### 场景一：职位页面发现\n\n当需要在招聘网站中查找所有职位相关页面时：\n\n```python\npayload = {\n \"url\": \"https://career.oxylabs.io\",\n \"search_keywords\": [\"career\", \"jobs\", \"vacancy\"],\n \"user_prompt\": \"job ad pages\",\n \"max_crawl_depth\": 2,\n \"limit\": 10,\n \"geo_location\": \"Germany\",\n \"render_javascript\": False,\n \"include_sitemap\": True,\n}\n```\n\n资料来源：[readme.md](https://github.com/oxylabs/oxylabs-ai-studio-py/blob/main/readme.md)\n\n### 场景二：电商产品分类映射\n\n对于电商站点，需要发现所有产品分类页面：\n\n```python\npayload = {\n \"url\": \"https://shop.example.com\",\n \"search_keywords\": [\"category\", \"products\", \"collections\"],\n \"user_prompt\": \"product category pages\",\n \"max_crawl_depth\": 3,\n \"limit\": 50,\n \"include_sitemap\": True,\n \"allow_subdomains\": False,\n}\n```\n\n## 与其他模块的协作\n\nAI-Map 通常作为数据采集流程的起始环节：\n\n```mermaid\ngraph LR\n A[AI-Map] --> B[发现目标 URL 列表]\n B --> C[AI-Scraper]\n C --> D[提取页面内容]\n D --> E[AI-Crawler]\n E --> F[深度数据采集]\n```\n\n典型工作流：\n\n1. **使用 AI-Map 发现相关页面** - 通过关键词定位目标 URL\n2. **使用 AI-Scraper 提取结构化数据** - 对单个或少量页面进行精确提取\n3. **使用 AI-Crawler 进行大规模采集** - 对发现的所有相关页面进行批量内容提取\n\n## 错误处理\n\nAI-Map 抛出的主要异常类型：\n\n| 异常类型 | 触发条件 | 处理建议 |\n|----------|----------|----------|\n| ValueError | 必要参数缺失或格式错误 | 检查 payload 配置 |\n| Exception | API 请求失败 | 检查网络连接和 API Key 有效性 |\n| TimeoutError | 任务执行超时 | 增加 timeout 配置或减少 limit |\n\n## 最佳实践\n\n1. **渐进式探索**：从 `max_crawl_depth=1` 开始，确认结果符合预期后再逐步增加深度\n2. **精准关键词**：使用精确的路径关键词可大幅减少无关页面的发现\n3. **积分控制**：通过 `max_credits` 设置消费上限，避免意外超支\n4. **sitemap 优先**：大多数站点 sitemap 包含完整结构，建议保持 `include_sitemap=True`\n5. **地理定位**：根据目标用户群体设置 `geo_location`，获取区域性内容\n\n---\n\n\n\n## Browser Agent 文档\n\n### 相关页面\n\n相关主题：[AI-Scraper 文档](#ai-scraper), [Schema 生成指南](#schema-generation)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [src/oxylabs_ai_studio/apps/browser_agent.py](https://github.com/oxylabs/oxylabs-ai-studio-py/blob/main/src/oxylabs_ai_studio/apps/browser_agent.py)\n- [examples/browser_agent.py](https://github.com/oxylabs/oxylabs-ai-studio-py/blob/main/examples/browser_agent.py)\n- [agentic_code_guide.md](https://github.com/oxylabs/oxylabs-ai-studio-py/blob/main/agentic_code_guide.md)\n- [readme.md](https://github.com/oxylabs/oxylabs-ai-studio-py/blob/main/readme.md)\n \n\n# Browser Agent 文档\n\n## 概述\n\nBrowser Agent 是 Oxylabs AI Studio Python SDK 中的一个核心模块，提供基于 AI 的浏览器自动化能力。该模块能够控制浏览器执行点击、滚动、导航等操作，并根据自然语言提示完成复杂的数据提取任务。\n\nBrowser Agent 的主要特点包括：\n\n- 支持同步和异步两种调用方式\n- 内置自动模式识别功能，可根据输出格式自动生成 JSON Schema\n- 支持多种输出格式（JSON、Markdown、HTML、Screenshot、CSV、Toon）\n- 提供地理位置模拟能力，可设置代理位置\n- 支持 JavaScript 渲染\n- 可自定义 User-Agent 请求头\n\n资料来源：[readme.md](https://github.com/oxylabs/oxylabs-ai-studio-py/blob/main/readme.md)\n\n## 架构设计\n\n### 组件关系图\n\n```mermaid\ngraph TD\n A[BrowserAgent] --> B[API 调用层]\n B --> C[轮询机制]\n C --> D{状态检查}\n D -->|processing| E[等待继续轮询]\n D -->|completed| F[返回 BrowserAgentJob]\n D -->|failed| G[返回失败状态]\n E --> D\n B --> H[Async Client]\n H --> I[异步轮询机制]\n I --> J{异步状态检查}\n J -->|processing| K[异步等待]\n J -->|completed| L[返回 BrowserAgentJob]\n J -->|failed| M[返回失败状态]\n```\n\n### 核心数据模型\n\nBrowser Agent 使用 Pydantic 模型定义返回数据结构：\n\n| 模型名称 | 字段 | 类型 | 说明 |\n|---------|------|------|------|\n| `DataModel` | type | `Literal[\"json\", \"markdown\", \"html\", \"screenshot\", \"csv\"]` | 输出内容类型 |\n| `DataModel` | content | `dict[str, Any] \\| str \\| None` | 实际返回的数据内容 |\n| `BrowserAgentJob` | run_id | `str` | 任务唯一标识符 |\n| `BrowserAgentJob` | message | `str \\| None` | 错误信息或状态消息 |\n| `BrowserAgentJob` | data | `DataModel \\| None` | 结构化的任务数据 |\n\n资料来源：[agentic_code_guide.md](https://github.com/oxylabs/oxylabs-ai-studio-py/blob/main/agentic_code_guide.md)\n\n## 安装与初始化\n\n### 安装 SDK\n\n```bash\npip install oxylabs-ai-studio\n```\n\n### 初始化 Browser Agent\n\n```python\nfrom oxylabs_ai_studio.apps.browser_agent import BrowserAgent\n\nbrowser_agent = BrowserAgent(api_key=\"\")\n```\n\n## API 参数说明\n\n### run 方法参数\n\n| 参数名 | 类型 | 必填 | 默认值 | 说明 |\n|--------|------|------|--------|------|\n| url | str | 是 | - | 目标网页 URL |\n| user_prompt | str | 是 | - | 执行浏览器操作的自然语言提示 |\n| output_format | Literal[\"json\", \"markdown\", \"html\", \"screenshot\", \"csv\", \"toon\"] | 否 | \"markdown\" | 输出格式 |\n| schema | dict \\| None | 否 | None | JSON Schema（当 output_format 为 \"json\" 时必填） |\n| geo_location | str | 否 | None | 代理位置（ISO2 格式或国家名称） |\n| render_javascript | bool \\| str | 否 | False | JavaScript 渲染设置，可设为 \"auto\" 自动检测 |\n| user_agent | str | 否 | None | 自定义 User-Agent 请求头 |\n\n资料来源：[readme.md](https://github.com/oxylabs/oxylabs-ai-studio-py/blob/main/readme.md)\n\n### generate_schema 方法参数\n\n| 参数名 | 类型 | 必填 | 说明 |\n|--------|------|------|------|\n| prompt | str | 是 | 用于生成 JSON Schema 的自然语言描述 |\n\n## 使用示例\n\n### 同步调用示例\n\n```python\nfrom oxylabs_ai_studio.apps.browser_agent import BrowserAgent\n\nbrowser_agent = BrowserAgent(api_key=\"\")\n\n# 生成 Schema\nschema = browser_agent.generate_schema(\n prompt=\"game name, platform, review stars and price\"\n)\nprint(\"schema: \", schema)\n\n# 执行浏览器任务\nprompt = \"Find if there is game 'super mario odyssey' in the store. If there is, find the price. Use search bar to find the game.\"\nurl = \"https://sandbox.oxylabs.io/\"\nresult = browser_agent.run(\n url=url,\n user_prompt=prompt,\n output_format=\"json\",\n schema=schema,\n geo_location=\"Spain\",\n)\nprint(result.data)\n```\n\n资料来源：[examples/browser_agent.py](https://github.com/oxylabs/oxylabs-ai-studio-py/blob/main/examples/browser_agent.py)\n\n### 异步调用示例\n\n```python\nimport asyncio\nfrom oxylabs_ai_studio.apps.browser_agent import BrowserAgent\n\nbrowser_agent = BrowserAgent(api_key=\"\")\n\nasync def main():\n prompt = \"Find if there is game 'super mario odyssey' in the store.\"\n url = \"https://sandbox.oxylabs.io/\"\n result = await browser_agent.run_async(\n url=url,\n user_prompt=prompt,\n output_format=\"json\",\n schema={\"type\": \"object\", \"properties\": {\"page_url\": {\"type\": \"string\"}}, \"required\": []},\n )\n print(result.data)\n\nif __name__ == \"__main__\":\n asyncio.run(main())\n```\n\n资料来源：[agentic_code_guide.md](https://github.com/oxylabs/oxylabs-ai-studio-py/blob/main/agentic_code_guide.md)\n\n### 异步 Schema 生成\n\n```python\nimport asyncio\nfrom oxylabs_ai_studio.apps.browser_agent import BrowserAgent\n\nbrowser_agent = BrowserAgent(api_key=\"\")\n\nasync def main():\n schema = await browser_agent.generate_schema_async(\n prompt=\"game name, platform, review stars and price\"\n )\n print(\"Generated schema:\", schema)\n\nif __name__ == \"__main__\":\n asyncio.run(main())\n```\n\n## 执行流程\n\n```mermaid\nsequenceDiagram\n participant Client\n participant BrowserAgent\n participant API\n \n Client->>BrowserAgent: run(url, user_prompt, output_format, schema)\n BrowserAgent->>API: POST /browser-agent/run\n API-->>BrowserAgent: {run_id, status}\n BrowserAgent->>API: GET /browser-agent/run/data?run_id={run_id}\n API-->>BrowserAgent: status: processing\n Note over BrowserAgent: 轮询等待\n BrowserAgent->>API: GET /browser-agent/run/data?run_id={run_id}\n API-->>BrowserAgent: status: completed\n BrowserAgent-->>Client: BrowserAgentJob(data)\n```\n\n## 错误处理与超时\n\n### 超时机制\n\nBrowser Agent 内置超时检测，当请求超时时抛出 `TimeoutError`：\n\n```python\ntry:\n result = browser_agent.run(\n url=url,\n user_prompt=prompt,\n output_format=\"json\",\n schema=schema,\n )\nexcept TimeoutError as e:\n print(f\"请求超时: {e}\")\n```\n\n### 用户取消\n\n用户可通过键盘中断（KeyboardInterrupt）取消正在执行的爬取任务：\n\n```python\ntry:\n result = browser_agent.run(\n url=url,\n user_prompt=prompt,\n output_format=\"json\",\n schema=schema,\n )\nexcept KeyboardInterrupt:\n logger.info(\"[Cancelled] Browser agent was cancelled by user.\")\n```\n\n资料来源：[src/oxylabs_ai_studio/apps/browser_agent.py](https://github.com/oxylabs/oxylabs-ai-studio-py/blob/main/src/oxylabs_ai_studio/apps/browser_agent.py)\n\n## 返回值结构\n\n### 成功响应\n\n```python\nBrowserAgentJob(\n run_id=\"xxx-xxx-xxx\",\n message=None,\n data=DataModel(\n type=\"json\",\n content={\"game_name\": \"Super Mario Odyssey\", \"price\": \"$59.99\"}\n )\n)\n```\n\n### 失败响应\n\n```python\nBrowserAgentJob(\n run_id=\"xxx-xxx-xxx\",\n message=\"error_code\",\n data=None\n)\n```\n\n## 与其他模块的对比\n\n| 功能 | Browser Agent | AI Scraper | AI Crawler |\n|------|---------------|------------|------------|\n| 交互式操作 | ✅ 支持点击、滚动、导航 | ❌ 仅静态页面提取 | ❌ 仅静态页面爬取 |\n| 输出格式 | JSON, Markdown, HTML, Screenshot, CSV, Toon | JSON, Markdown, CSV, Screenshot, Toon | JSON, Markdown, CSV, Toon |\n| Schema 生成 | ✅ 内置 generate_schema | ✅ 内置 generate_schema | ✅ 内置 generate_schema |\n| 地理位置 | ✅ 支持 | ✅ 支持 | ✅ 支持 |\n| JavaScript 渲染 | ✅ 支持 | ✅ 支持 | ✅ 支持 |\n\n## 最佳实践\n\n1. **合理设置 user_prompt**：提示词应描述要执行的操作，而非单纯说明要提取的内容\n2. **使用 Schema 限制输出**：当需要结构化数据时，预先定义 JSON Schema\n3. **处理异步操作**：对于大量任务，优先使用 `run_async` 方法提高效率\n4. **设置合理的超时时间**：根据目标网站响应时间调整超时配置\n5. **地理位置选择**：根据目标网站的地区限制选择合适的 geo_location 参数\n\n## 限制与注意事项\n\n- Python 版本要求：3.10 及以上\n- 需要有效的 API Key\n- 部分功能可能产生额外的 API 调用费用\n- 地理位置参数需使用支持的 ISO2 格式或国家规范名称\n\n---\n\n\n\n## API 客户端架构\n\n### 相关页面\n\n相关主题：[数据模型](#data-models), [快速入门](#quick-start)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [src/oxylabs_ai_studio/client.py](https://github.com/oxylabs/oxylabs-ai-studio-py/blob/main/src/oxylabs_ai_studio/client.py)\n- [src/oxylabs_ai_studio/logger.py](https://github.com/oxylabs/oxylabs-ai-studio-py/blob/main/src/oxylabs_ai_studio/logger.py)\n- [src/oxylabs_ai_studio/settings.py](https://github.com/oxylabs/oxylabs-ai-studio-py/blob/main/src/oxylabs_ai_studio/settings.py)\n- [src/oxylabs_ai_studio/utils.py](https://github.com/oxylabs/oxylabs-ai-studio-py/blob/main/src/oxylabs_ai_studio/utils.py)\n- [src/oxylabs_ai_studio/apps/browser_agent.py](https://github.com/oxylabs/oxylabs-ai-studio-py/blob/main/src/oxylabs_ai_studio/apps/browser_agent.py)\n \n\n# API 客户端架构\n\n## 概述\n\nOxylabs AI Studio Python SDK 的核心架构采用**面向对象继承模式**，所有应用模块均继承自统一的基类 `OxyStudioAIClient`。该架构设计遵循**单一职责原则**，将 HTTP 通信、日志记录、配置管理和业务逻辑分离到不同的模块中，实现了高度的内聚性和低耦合性。\n\n客户端架构支持以下核心功能：\n\n- 同步与异步双接口设计\n- 自动重试与超时处理\n- 结构化数据提取\n- 代理地理位置定位\n- JavaScript 渲染支持\n\n## 架构分层\n\n```mermaid\ngraph TD\n subgraph \"表现层 (Presentation Layer)\"\n A[应用模块: AiCrawler
AiScraper
AiSearch
BrowserAgent
AiMap]\n end\n \n subgraph \"核心客户端层 (Core Client Layer)\"\n B[OxyStudioAIClient]\n end\n \n subgraph \"工具层 (Utility Layer)\"\n C[logger.py]\n D[settings.py]\n E[utils.py]\n end\n \n subgraph \"数据模型层 (Data Model Layer)\"\n F[models.py
SchemaResponse
AiScraperJob
BrowserAgentJob]\n end\n \n subgraph \"外部服务层\"\n G[Oxylabs AI Studio API]\n end\n \n A --> B\n B --> C\n B --> D\n B --> E\n B --> F\n B --> G\n```\n\n## 核心组件详解\n\n### 1. OxyStudioAIClient 基类\n\n`OxyStudioAIClient` 是所有应用模块的父类，位于 `src/oxylabs_ai_studio/client.py`。该类封装了所有与 API 通信的通用逻辑。\n\n#### 核心职责\n\n| 职责 | 说明 |\n|------|------|\n| API 认证 | 管理 API Key 的存储与传递 |\n| HTTP 请求 | 封装 GET/POST 请求方法 |\n| 响应处理 | 统一处理 API 响应格式 |\n| 错误处理 | 异常捕获与日志记录 |\n| 重试机制 | 自动重试失败的请求 |\n\n#### 继承结构\n\n```python\nclass OxyStudioAIClient:\n def __init__(self, api_key: str | None = None):\n \"\"\"初始化客户端实例\"\"\"\n pass\n \n def get_client(self) -> httpx.Client:\n \"\"\"获取 HTTP 客户端实例\"\"\"\n pass\n \n def call_api(self, client, url, method, **kwargs) -> httpx.Response:\n \"\"\"调用 API 的通用方法\"\"\"\n pass\n```\n\n所有应用模块继承此基类：\n\n```python\nclass BrowserAgent(OxyStudioAIClient):\n def __init__(self, api_key: str | None = None):\n super().__init__(api_key=api_key)\n\nclass AiScraper(OxyStudioAIClient):\n # 继承相同模式\n pass\n\nclass AiCrawler(OxyStudioAIClient):\n # 继承相同模式\n pass\n```\n\n资料来源：[src/oxylabs_ai_studio/client.py](https://github.com/oxylabs/oxylabs-ai-studio-py/blob/main/src/oxylabs_ai_studio/client.py)\n\n### 2. 应用模块\n\nSDK 提供五个主要应用模块，每个模块对应特定的数据采集场景：\n\n| 模块 | 功能 | 输出格式 |\n|------|------|----------|\n| AiCrawler | 网站爬取与深度遍历 | json, markdown, csv, toon |\n| AiScraper | 单页面结构化提取 | json, markdown, csv, screenshot, toon |\n| AiSearch | 搜索引擎结果抓取 | json (含 content 选项) |\n| BrowserAgent | 浏览器自动化操作 | json, markdown |\n| AiMap | 站点地图发现 | - |\n\n#### 同步与异步接口模式\n\n每个应用模块同时提供同步 (`run`/`scrape`/`search`) 和异步 (`run_async`/`scrape_async`/`search_async`) 接口：\n\n```python\n# 同步接口\nresult = scraper.scrape(url=url, output_format=\"markdown\")\n\n# 异步接口\nresult = await scraper.scrape_async(url=url, output_format=\"markdown\")\n```\n\n### 3. 日志系统\n\n日志模块位于 `src/oxylabs_ai_studio/logger.py`，采用 Python 标准库 `logging` 实现。\n\n#### 日志级别配置\n\n```python\nlogger = get_logger(__name__)\n\nlogger.info(\"正在生成 schema\")\nlogger.error(f\"API 调用失败: {response.text}\")\n```\n\n#### 日志输出目标\n\n- 控制台 (Console)\n- 可配置的日志文件\n\n### 4. 配置管理\n\n`src/oxylabs_ai_studio/settings.py` 负责管理 SDK 全局配置：\n\n| 配置项 | 类型 | 说明 |\n|--------|------|------|\n| API_BASE_URL | str | API 基础 URL |\n| TIMEOUT | int | 请求超时时间（秒） |\n| MAX_RETRIES | int | 最大重试次数 |\n| POLL_INTERVAL | int | 轮询间隔（秒） |\n\n### 5. 工具函数\n\n`src/oxylabs_ai_studio/utils.py` 提供通用辅助函数：\n\n- 数据验证\n- 响应格式化\n- 错误码映射\n\n## 请求流程\n\n### 标准请求流程\n\n```mermaid\nsequenceDiagram\n participant User as 用户代码\n participant App as 应用模块\n participant Client as OxyStudioAIClient\n participant API as Oxylabs API\n participant Response as 响应数据\n\n User->>App: 调用方法 (scrape/crawl/search)\n App->>App: 参数验证与格式化\n App->>Client: call_api(client, url, method, body)\n Client->>API: HTTP POST/GET 请求\n API-->>Client: 202 (处理中) 或 200 (完成)\n \n alt 长任务 (状态码 202)\n Client->>Client: 轮询直到完成\n loop 轮询\n Client->>API: GET /status\n API-->>Client: status: processing\n end\n end\n \n Client-->>App: 返回响应数据\n App-->>User: 返回 Job 对象\n```\n\n### 长任务轮询机制\n\n对于需要较长时间处理的任务（如爬取大量页面），SDK 采用轮询机制：\n\n```python\nPOLL_INTERVAL_SECONDS = 5\nPOLL_MAX_ATTEMPTS = 120 # 默认 10 分钟超时\n```\n\n状态转换：\n\n```mermaid\nstateDiagram-v2\n [*] --> Submitted: POST /run\n Submitted --> Processing: 202 响应\n Processing --> Processing: 继续轮询\n Processing --> Completed: 200 + status=completed\n Processing --> Failed: status=failed\n Completed --> [*]\n Failed --> [*]\n```\n\n资料来源：[src/oxylabs_ai_studio/apps/browser_agent.py:6-7](https://github.com/oxylabs/oxylabs-ai-studio-py/blob/main/src/oxylabs_ai_studio/apps/browser_agent.py)\n\n## 数据模型\n\n### 通用响应模型\n\n所有应用模块返回统一的 Job 对象结构：\n\n```python\nclass AiScraperJob(BaseModel):\n run_id: str\n message: str | None = None\n data: str | dict | None\n\nclass BrowserAgentJob(BaseModel):\n run_id: str\n message: str | None = None\n data: DataModel | None = None\n\nclass DataModel(BaseModel):\n type: Literal[\"json\", \"markdown\", \"html\", \"screenshot\", \"csv\"]\n content: dict[str, Any] | str | None\n```\n\n### Schema 响应模型\n\n```python\nclass SchemaResponse(BaseModel):\n schema: dict[str, Any]\n user_prompt: str\n```\n\n## 认证机制\n\nAPI 认证采用 **API Key** 方式，通过 HTTP Header 传递：\n\n```python\nheaders = {\n \"Authorization\": f\"Bearer {self.api_key}\",\n \"Content-Type\": \"application/json\"\n}\n```\n\n初始化方式：\n\n```python\n# 方式一：直接传入\nscraper = AiScraper(api_key=\"your-api-key\")\n\n# 方式二：环境变量\n# 设置环境变量 OXyLABS_API_KEY\nscraper = AiScraper() # 自动从环境变量读取\n```\n\n## 错误处理\n\n### 错误类型\n\n| 错误类型 | 触发条件 | 处理方式 |\n|----------|----------|----------|\n| `ValueError` | 参数验证失败 | 检查输入参数 |\n| `httpx.HTTPStatusError` | HTTP 4xx/5xx 错误 | 检查 API Key 和网络 |\n| `TimeoutError` | 请求超时 | 增加超时时间 |\n| `KeyboardInterrupt` | 用户取消操作 | 优雅退出 |\n\n### 参数验证示例\n\n```python\ndef scrape(self, ..., output_format: str, schema: dict | None = None):\n if output_format in [\"json\", \"csv\", \"toon\"] and schema is None:\n raise ValueError(\n \"schema is required when output_format is json, csv or toon.\"\n )\n```\n\n## 高级配置\n\n### 地理位置定位\n\n通过 `geo_location` 参数指定代理位置：\n\n```python\nresult = scraper.scrape(\n url=\"https://example.com\",\n geo_location=\"Germany\", # 或 \"DE\" ISO2 格式\n)\n```\n\n支持的格式：\n- ISO 2-letter 代码：`\"DE\"`, `\"US\"`, `\"IT\"`\n- 国家名称：`\"Germany\"`, `\"United States\"`\n\n### JavaScript 渲染\n\n```python\n# 禁用 JS 渲染 (默认)\nrender_javascript=False\n\n# 启用 JS 渲染\nrender_javascript=True\n\n# 自动检测\nrender_javascript=\"auto\"\n```\n\n### 结构化提取\n\n使用 JSON Schema 定义输出结构：\n\n```python\nschema = {\n \"type\": \"object\",\n \"properties\": {\n \"title\": {\"type\": \"string\"},\n \"price\": {\"type\": \"string\"},\n \"features\": {\n \"type\": \"array\",\n \"items\": {\"type\": \"string\"}\n }\n },\n \"required\": [\"title\", \"price\"]\n}\n```\n\n或使用 Pydantic 模型自动生成 Schema：\n\n```python\nfrom pydantic import BaseModel, Field\n\nclass Product(BaseModel):\n title: str = Field(description=\"产品名称\")\n price: str = Field(description=\"产品价格\")\n\nschema = Product.model_json_schema()\n```\n\n## 使用示例\n\n### 基础用法\n\n```python\nfrom oxylabs_ai_studio.apps.ai_scraper import AiScraper\n\nscraper = AiScraper(api_key=\"\")\nresult = scraper.scrape(\n url=\"https://example.com/products/1\",\n output_format=\"markdown\",\n)\nprint(result.data)\n```\n\n### 异步用法\n\n```python\nimport asyncio\nfrom oxylabs_ai_studio.apps.ai_scraper import AiScraper\n\nscraper = AiScraper(api_key=\"\")\n\nasync def main():\n result = await scraper.scrape_async(\n url=\"https://example.com/products/1\",\n output_format=\"json\",\n schema={\"type\": \"object\", \"properties\": {\"title\": {\"type\": \"string\"}}},\n )\n print(result.data)\n\nasyncio.run(main())\n```\n\n## 最佳实践\n\n1. **API Key 管理**：使用环境变量存储 API Key，避免硬编码\n2. **错误处理**：捕获特定异常类型，进行针对性处理\n3. **重试机制**：实现指数退避策略处理临时性失败\n4. **超时配置**：根据任务复杂度合理设置超时时间\n5. **异步批量处理**：大量请求时使用异步接口提高吞吐量\n\n---\n\n\n\n## 数据模型\n\n### 相关页面\n\n相关主题：[API 客户端架构](#api-client), [Schema 生成指南](#schema-generation)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [src/oxylabs_ai_studio/apps/ai_search.py](https://github.com/oxylabs/oxylabs-ai-studio-py/blob/main/src/oxylabs_ai_studio/apps/ai_search.py)\n- [src/oxylabs_ai_studio/apps/ai_scraper.py](https://github.com/oxylabs/oxylabs-ai-studio-py/blob/main/src/oxylabs_ai_studio/apps/ai_scraper.py)\n- [src/oxylabs_ai_studio/apps/ai_crawler.py](https://github.com/oxylabs/oxylabs-ai-studio-py/blob/main/src/oxylabs_ai_studio/apps/ai_crawler.py)\n- [src/oxylabs_ai_studio/apps/ai_map.py](https://github.com/oxylabs/oxylabs-ai-studio-py/blob/main/src/oxylabs_ai_studio/apps/ai_map.py)\n- [agentic_code_guide.md](https://github.com/oxylabs/oxylabs-ai-studio-py/blob/main/agentic_code_guide.md)\n- [examples/crawl_pydantic_schema.py](https://github.com/oxylabs/oxylabs-ai-studio-py/blob/main/examples/crawl_pydantic_schema.py)\n \n\n# 数据模型\n\n## 概述\n\nOxylabs AI Studio Python SDK 的数据模型是整个SDK架构的核心组成部分，定义了各应用模块返回数据结构的一致性模式。SDK采用Pydantic作为数据验证库，为所有API响应提供类型安全的数据结构。\n\n数据模型系统包含两类核心模型：作业模型（Job Models）和数据模型（Data Models）。作业模型封装了API调用的完整响应信息，包括任务标识符、状态消息和实际数据内容。数据模型则定义了具体输出的格式和结构，支持多种输出类型如JSON、Markdown、HTML、CSV和Screenshot。\n\n## 核心数据模型架构\n\n### 模型继承关系\n\n```mermaid\ngraph TD\n A[BaseModel - Pydantic] --> B[AiSearchJob]\n A --> C[AiScraperJob]\n A --> D[AiCrawlerJob]\n A --> E[AiMapJob]\n A --> F[BrowserAgentJob]\n \n G[DataModel] --> C\n G --> F\n \n H[SchemaResponse] --> I[内部响应模型]\n```\n\n## 作业模型详解\n\n### AiSearchJob 搜索作业模型\n\n`AiSearchJob` 是搜索功能的返回模型，用于封装SERP（搜索引擎结果页面）搜索操作的结果。该模型继承自Pydantic的BaseModel，确保数据类型的安全性。\n\n| 字段名 | 类型 | 描述 |\n|--------|------|------|\n| run_id | str | 任务唯一标识符，用于追踪和查询任务状态 |\n| message | str \\| None | 状态消息或错误代码 |\n| data | Any \\| None | 搜索结果数据内容 |\n\n```python\nclass AiSearchJob(BaseModel):\n run_id: str\n message: str | None = None\n data: Any | None = None\n```\n\n资料来源：[src/oxylabs_ai_studio/apps/ai_search.py:1-100]()\n\n搜索功能支持两种模式：标准搜索和即时搜索。即时搜索在满足`limit <= 10`且`return_content=False`条件时自动启用，直接返回结果而无需轮询状态。\n\n### AiScraperJob 网页抓取作业模型\n\n`AiScraperJob` 是网页抓取功能的核心返回模型，与搜索模型类似但增加了对多种输出格式的支持。\n\n| 字段名 | 类型 | 描述 |\n|--------|------|------|\n| run_id | str | 任务唯一标识符 |\n| message | str \\| None | 错误信息或状态描述 |\n| data | str \\| dict \\| None | 根据output_format返回不同类型的数据 |\n\n```python\nclass AiScraperJob(BaseModel):\n run_id: str\n message: str | None = None\n data: str | dict | None\n```\n\n资料来源：[agentic_code_guide.md](https://github.com/oxylabs/oxylabs-ai-studio-py/blob/main/agentic_code_guide.md)\n\nAiScraperJob的data字段根据output_format参数呈现不同类型：JSON格式返回字典对象，Markdown格式返回字符串，CSV格式返回逗号分隔的字符串，Screenshot格式返回Base64编码的字符串。\n\n### AiCrawlerJob 网站爬取作业模型\n\n`AiCrawlerJob` 用于封装网站爬取功能的结果，支持批量URL的数据提取。该模型返回的data字段为列表类型，每个元素代表一个页面的提取结果。\n\n```python\nclass AiCrawlerJob(BaseModel):\n run_id: str\n message: str | None = None\n data: list[Any] | None = None\n```\n\n资料来源：[src/oxylabs_ai_studio/apps/ai_crawler.py:1-100]()\n\n爬取功能支持自定义Pydantic Schema进行结构化数据提取，可以定义复杂的嵌套数据类型：\n\n```python\nclass ProxyPlan(BaseModel):\n name: str = Field(description=\"The name of the proxy plan\")\n price: str = Field(description=\"The price of the proxy plan\")\n features: list[str] = Field(description=\"The features of the proxy plan\")\n\nclass ProxyPlans(BaseModel):\n proxy_plans: list[ProxyPlan] = Field(description=\"The proxy plans\")\n```\n\n资料来源：[examples/crawl_pydantic_schema.py:1-25]()\n\n### AiMapJob 站点映射作业模型\n\n`AiMapJob` 是站点映射功能的返回模型，用于生成网站结构地图。该模型返回的数据为字典类型，包含URL与关键词的映射关系。\n\n```python\nclass AiMapJob(BaseModel):\n run_id: str\n message: str | None = None\n data: dict | None = None\n```\n\n资料来源：[src/oxylabs_ai_studio/apps/ai_map.py:1-100]()\n\n### BrowserAgentJob 浏览器代理作业模型\n\n`BrowserAgentJob` 是浏览器代理功能的核心模型，包含DataModel嵌套结构用于封装结构化的页面数据。\n\n```python\nclass DataModel(BaseModel):\n type: Literal[\"json\", \"markdown\", \"html\", \"screenshot\", \"csv\"]\n content: dict[str, Any] | str | None\n\nclass BrowserAgentJob(BaseModel):\n run_id: str\n message: str | None = None\n data: DataModel | None = None\n```\n\n资料来源：[agentic_code_guide.md](https://github.com/oxylabs/oxylabs-ai-studio-py/blob/main/agentic_code_guide.md)\n\n## Schema生成与响应模型\n\n### Schema生成机制\n\nSDK提供智能Schema生成功能，允许用户通过自然语言描述期望的数据结构，系统自动生成对应的JSON Schema。\n\n```mermaid\ngraph LR\n A[自然语言提示] --> B[generate_schema方法]\n B --> C[POST /scrape/schema]\n C --> D[API响应]\n D --> E[openapi_schema]\n E --> F[用于scrape/crawl]\n```\n\n```python\ndef generate_schema(self, prompt: str) -> dict[str, Any] | None:\n logger.info(\"Generating schema\")\n body = {\"user_prompt\": prompt}\n response = self.call_api(\n client=self.get_client(), url=\"/scrape/schema\", method=\"POST\", body=body\n )\n if response.status_code != 200:\n raise Exception(f\"Failed to generate schema: {response.text}\")\n json_response: SchemaResponse = response.json()\n return json_response.get(\"openapi_schema\", None)\n```\n\n资料来源：[src/oxylabs_ai_studio/apps/ai_scraper.py:1-100]()\n\n### SchemaResponse 响应模型\n\n```python\nclass SchemaResponse(BaseModel):\n openapi_schema: dict[str, Any] | None\n```\n\nSchema生成功能同样支持异步调用，通过`generate_schema_async`方法实现：\n\n```python\nasync def generate_schema_async(self, prompt: str) -> dict[str, Any] | None:\n logger.info(\"Generating schema (async)\")\n body = {\"user_prompt\": prompt}\n async with self.async_client() as client:\n response = await self.call_api_async(\n client=client, url=\"/crawl/generate-params\", method=\"POST\", body=body\n )\n # ...\n```\n\n资料来源：[src/oxylabs_ai_studio/apps/ai_crawler.py:1-100]()\n\n## 输出格式与数据类型映射\n\n### 支持的输出格式\n\n| 格式 | 描述 | data字段类型 |\n|------|------|--------------|\n| json | 结构化JSON数据 | dict |\n| markdown | Markdown格式文本 | str |\n| html | 原始HTML内容 | str |\n| screenshot | Base64编码图片 | str |\n| csv | 逗号分隔值格式 | str |\n| toon | 特殊格式 | dict |\n\n### 格式选择指南\n\n```mermaid\ngraph TD\n A[需要结构化数据?] --> |是| B[output_format=json]\n A --> |否| C[需要渲染后内容?]\n C --> |是| D[output_format=screenshot]\n C --> |否| E[需要原始HTML?]\n E --> |是| F[output_format=html]\n E --> |否| G[output_format=markdown]\n \n B --> H[需要schema参数]\n G --> I[可选schema]\n```\n\n选择输出格式时需考虑以下因素：\n\n1. **JSON格式**：需要提供schema参数定义数据结构，适合程序化处理\n2. **Markdown格式**：适合内容提取和文本分析，无需schema\n3. **Screenshot格式**：适合需要渲染JavaScript的动态内容\n4. **CSV格式**：适合表格数据导出，需要schema定义列结构\n\n资料来源：[readme.md](https://github.com/oxylabs/oxylabs-ai-studio-py/blob/main/readme.md)\n\n## 状态轮询与响应处理\n\n### 异步任务状态流程\n\n```mermaid\nstateDiagram-v2\n [*] --> 提交任务\n 提交任务 --> processing: 状态检查\n processing --> processing: 轮询中\n processing --> completed: status==\"completed\"\n processing --> failed: status==\"failed\"\n completed --> [*]\n failed --> [*]\n```\n\n所有作业模型都采用轮询机制获取最终结果：\n\n```python\ndef scrape(self, url: str, ...) -> AiScraperJob:\n # 提交抓取任务\n response = self.call_api(...)\n run_id = response.json()[\"run_id\"]\n \n # 轮询状态直到完成\n while True:\n get_response = self.call_api(...)\n resp_body = get_response.json()\n \n if resp_body[\"status\"] == \"completed\":\n return AiScraperJob(\n run_id=run_id,\n message=resp_body.get(\"error_code\", None),\n data=resp_body.get(\"data\", None),\n )\n \n if resp_body[\"status\"] == \"failed\":\n return AiScraperJob(\n run_id=run_id,\n message=resp_body.get(\"error_code\", None),\n data=None,\n )\n \n time.sleep(POLL_INTERVAL_SECONDS)\n```\n\n资料来源：[src/oxylabs_ai_studio/apps/ai_scraper.py:1-100]()\n\n### 响应状态码处理\n\n| HTTP状态码 | 含义 | SDK处理 |\n|------------|------|---------|\n| 200 | 成功 | 解析JSON并构建Job模型 |\n| 202 | 处理中 | 继续轮询等待 |\n| 4xx | 客户端错误 | 抛出异常 |\n| 5xx | 服务器错误 | 轮询重试 |\n\n## 错误处理与数据验证\n\n### 数据验证机制\n\n所有数据模型使用Pydantic进行运行时类型验证：\n\n```python\nfrom pydantic import BaseModel, Field\n\nclass ProxyPlan(BaseModel):\n name: str = Field(description=\"The name of the proxy plan\")\n price: str = Field(description=\"The price of the proxy plan\")\n features: list[str] = Field(description=\"The features of the proxy plan\")\n```\n\n资料来源：[examples/crawl_pydantic_schema.py:1-25]()\n\n### 异常处理策略\n\n| 异常类型 | 触发条件 | 处理方式 |\n|----------|----------|----------|\n| ValueError | 参数验证失败 | 检查输入参数 |\n| TimeoutError | 轮询超时 | 增加max_credits或检查网络 |\n| KeyboardInterrupt | 用户取消 | 优雅退出并记录日志 |\n| Exception | API错误 | 查看message字段获取详情 |\n\n## 最佳实践\n\n### Schema设计建议\n\n1. 使用明确的Field描述帮助AI理解字段含义\n2. 嵌套模型不要超过3层深度\n3. 数组字段使用有意义的复数名词命名\n4. 始终指定required字段列表\n\n### 数据模型使用示例\n\n```python\nfrom oxylabs_ai_studio.apps.ai_crawler import AiCrawler\n\ncrawler = AiCrawler(api_key=\"\")\n\n# 使用Pydantic模型定义Schema\nschema = ProxyPlans.model_json_schema()\n\nresult = crawler.crawl(\n url=\"https://oxylabs.io\",\n user_prompt=\"Find all pages with proxy products pricing\",\n output_format=\"json\",\n schema=schema,\n)\n\n# 安全访问结果\nfor item in result.data:\n print(item, \"\\n\")\n```\n\n资料来源：[examples/crawl_pydantic_schema.py:1-30]()\n\n## 相关文档\n\n- [AI-Scraper使用指南](agentic_code_guide.md)\n- [示例代码集合](examples/)\n- [API参考文档](readme.md)\n\n---\n\n\n\n## Schema 生成指南\n\n### 相关页面\n\n相关主题：[AI-Scraper 文档](#ai-scraper), [Browser Agent 文档](#browser-agent), [数据模型](#data-models)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [src/oxylabs_ai_studio/apps/ai_scraper.py](https://github.com/oxylabs/oxylabs-ai-studio-py/blob/main/src/oxylabs_ai_studio/apps/ai_scraper.py)\n- [src/oxylabs_ai_studio/apps/browser_agent.py](https://github.com/oxylabs/oxylabs-ai-studio-py/blob/main/src/oxylabs_ai_studio/apps/browser_agent.py)\n- [src/oxylabs_ai_studio/apps/ai_crawler.py](https://github.com/oxylabs/oxylabs-ai-studio-py/blob/main/src/oxylabs_ai_studio/apps/ai_crawler.py)\n- [examples/scrape_generated_schema.py](https://github.com/oxylabs/oxylabs-ai-studio-py/blob/main/examples/scrape_generated_schema.py)\n- [examples/crawl_generated_schema.py](https://github.com/oxylabs/oxylabs-ai-studio-py/blob/main/examples/crawl_generated_schema.py)\n- [examples/browser_agent.py](https://github.com/oxylabs/oxylabs-ai-studio-py/blob/main/examples/browser_agent.py)\n \n\n# Schema 生成指南\n\n## 概述\n\nSchema 生成功能是 oxylabs AI Studio SDK 中的核心特性之一，它允许用户通过自然语言描述自动生成符合 OpenAPI 规范的 JSON Schema，从而实现结构化数据提取。该功能简化了传统手动编写复杂 Schema 的流程，使开发者能够快速定义期望提取的数据结构。\n\nSchema 生成功能在以下三个主要应用模块中可用：\n\n- **AiScraper** - 单页面数据抓取\n- **AiCrawler** - 整站爬取\n- **BrowserAgent** - 浏览器代理操作\n\n## 工作原理\n\nSchema 生成采用自然语言处理技术，将用户的描述性提示转换为标准化的 JSON Schema。生成的 Schema 遵循 OpenAPI 规范，可直接用于指定输出格式为 `json`、`csv` 或 `toon` 时的结构化数据提取。\n\n```mermaid\ngraph LR\n A[自然语言提示] --> B[Schema 生成 API]\n B --> C[JSON Schema]\n C --> D[结构化数据提取]\n \n style A fill:#e1f5fe\n style B fill:#b3e5fc\n style C fill:#81d4fa\n style D fill:#4fc3f7\n```\n\n## 使用方法\n\n### AiScraper 中的 Schema 生成\n\nAiScraper 模块提供了 `generate_schema()` 方法，用于为单页面抓取生成 Schema。\n\n**同步调用示例：**\n\n```python\nfrom oxylabs_ai_studio.apps.ai_scraper import AiScraper\n\nscraper = AiScraper(api_key=\"\")\n\n# 生成 Schema\nschema = scraper.generate_schema(\n prompt=\"want to parse developer, platform, type, price game title, genre (array) and description\"\n)\nprint(f\"Generated schema: {schema}\")\n\n# 使用生成的 Schema 进行抓取\nurl = \"https://sandbox.oxylabs.io/products/3\"\nresult = scraper.scrape(\n url=url,\n output_format=\"json\",\n schema=schema,\n render_javascript=False,\n)\nprint(result)\n```\n\n**参数说明：**\n\n| 参数 | 类型 | 必填 | 说明 |\n|------|------|------|------|\n| prompt | str | 是 | 自然语言描述，指定需要提取的字段及其类型 |\n\n**生成的 Schema 示例：**\n\n```json\n{\n \"type\": \"object\",\n \"properties\": {\n \"developer\": {\"type\": \"string\"},\n \"platform\": {\"type\": \"string\"},\n \"type\": {\"type\": \"string\"},\n \"price\": {\"type\": \"string\"},\n \"game_title\": {\"type\": \"string\"},\n \"genre\": {\"type\": \"array\", \"items\": {\"type\": \"string\"}},\n \"description\": {\"type\": \"string\"}\n },\n \"required\": []\n}\n```\n\n资料来源：[examples/scrape_generated_schema.py](https://github.com/oxylabs/oxylabs-ai-studio-py/blob/main/examples/scrape_generated_schema.py)\n\n### BrowserAgent 中的 Schema 生成\n\nBrowserAgent 模块同样支持 Schema 生成，适用于需要浏览器交互的场景。\n\n**使用示例：**\n\n```python\nfrom oxylabs_ai_studio.apps.browser_agent import BrowserAgent\n\nbrowser_agent = BrowserAgent(api_key=\"\")\n\n# 生成 Schema\nschema = browser_agent.generate_schema(\n prompt=\"game name, platform, review stars and price\"\n)\nprint(\"schema: \", schema)\n\n# 使用生成的 Schema 执行浏览器操作\nprompt = \"Find if there is game 'super mario odyssey' in the store. If there is, find the price. Use search bar to find the game.\"\nurl = \"https://sandbox.oxylabs.io/\"\nresult = browser_agent.run(\n url=url,\n user_prompt=prompt,\n output_format=\"json\",\n schema=schema,\n)\nprint(result.data)\n```\n\n**参数说明：**\n\n| 参数 | 类型 | 必填 | 说明 |\n|------|------|------|------|\n| prompt | str | 是 | 自然语言描述，指定需要提取的字段 |\n\n资料来源：[examples/browser_agent.py](https://github.com/oxylabs/oxylabs-ai-studio-py/blob/main/examples/browser_agent.py)\n\n### AiCrawler 中的 Schema 生成\n\nAiCrawler 模块支持为整站爬取任务生成 Schema。\n\n**使用示例：**\n\n```python\nfrom oxylabs_ai_studio.apps.ai_crawler import AiCrawler\n\ncrawler = AiCrawler(api_key=\"\")\n\n# 生成 Schema\nschema = crawler.generate_schema(\n prompt=\"proxy plans which have name, price, and features\",\n)\nprint(\"schema: \", schema)\n\n# 使用生成的 Schema 进行爬取\nurl = \"https://oxylabs.io\"\nresult = crawler.crawl(\n url=url,\n user_prompt=\"Find all pages with proxy products pricing\",\n output_format=\"json\",\n schema=schema,\n render_javascript=False,\n)\nprint(\"Results:\")\nfor item in result.data:\n print(item, \"\\n\")\n```\n\n资料来源：[examples/crawl_generated_schema.py](https://github.com/oxylabs/oxylabs-ai-studio-py/blob/main/examples/crawl_generated_schema.py)\n\n## 配合 Pydantic 模型使用\n\n生成的 Schema 可以与 Pydantic 模型无缝配合使用，实现类型安全的数据验证。\n\n**示例：**\n\n```python\nfrom pydantic import BaseModel, Field\nfrom oxylabs_ai_studio.apps.ai_crawler import AiCrawler\n\ncrawler = AiCrawler(api_key=\"\")\n\nclass ProxyPlan(BaseModel):\n name: str = Field(description=\"The name of the proxy plan\")\n price: str = Field(description=\"The price of the proxy plan\")\n features: list[str] = Field(description=\"The features of the proxy plan\")\n\nclass ProxyPlans(BaseModel):\n proxy_plans: list[ProxyPlan] = Field(description=\"The proxy plans\")\n\nurl = \"https://oxylabs.io/\"\nresult = crawler.crawl(\n url=url,\n user_prompt=\"Find all pages with proxy products pricing\",\n output_format=\"json\",\n schema=ProxyPlans.model_json_schema(),\n render_javascript=False,\n)\n```\n\n资料来源：[examples/crawl_pydantic_schema.py](https://github.com/oxylabs/oxylabs-ai-studio-py/blob/main/examples/crawl_pydantic_schema.py)\n\n## 输出格式与 Schema 的关系\n\nSchema 生成功能与输出格式紧密相关。不同的输出格式对 Schema 有不同的要求：\n\n| 输出格式 | Schema 要求 | 返回数据类型 |\n|---------|------------|-------------|\n| json | 必须提供 | dict |\n| markdown | 可选 | str |\n| csv | 必须提供 | str |\n| toon | 必须提供 | str |\n| html | 可选 | str |\n| screenshot | 可选 | str |\n\n当输出格式为 `json`、`csv` 或 `toon` 时，必须提供有效的 JSON Schema。Schema 生成功能确保用户能够快速获得符合规范的 Schema 定义。\n\n资料来源：[agentic_code_guide.md](https://github.com/oxylabs/oxylabs-ai-studio-py/blob/main/agentic_code_guide.md)\n\n## 最佳实践\n\n### 1. 字段描述清晰化\n\n在编写 prompt 时，应明确指定每个字段的名称和数据类型：\n\n```python\n# 推荐：明确指定字段\nschema = scraper.generate_schema(\n prompt=\"extract product name (string), price (number), tags (array of strings), and description (string)\"\n)\n\n# 不推荐：描述模糊\nschema = scraper.generate_schema(\n prompt=\"extract product info\"\n)\n```\n\n### 2. 数组字段明确声明\n\n当需要提取数组类型数据时，应在 prompt 中明确说明：\n\n```python\nschema = scraper.generate_schema(\n prompt=\"game title, genre (array) and description\"\n)\n```\n\n### 3. 嵌套对象结构\n\n对于复杂的嵌套数据结构，可以详细描述层级关系：\n\n```python\nschema = crawler.generate_schema(\n prompt=\"proxy plans which have name, price, and features\",\n)\n```\n\n## 实现机制\n\nSchema 生成通过调用后端 API `/crawl/generate-params` 或类似的端点实现：\n\n```python\ndef generate_schema(self, prompt: str) -> dict[str, Any] | None:\n logger.info(\"Generating schema\")\n body = {\"user_prompt\": prompt}\n response = self.call_api(\n client=self.get_client(),\n url=\"/crawl/generate-params\",\n method=\"POST\",\n body=body,\n )\n if response.status_code != 200:\n raise Exception(f\"Failed to generate schema: {response.text}\")\n json_response: SchemaResponse = ...\n```\n\n资料来源：[src/oxylabs_ai_studio/apps/ai_crawler.py](https://github.com/oxylabs/oxylabs-ai-studio-py/blob/main/src/oxylabs_ai_studio/apps/ai_crawler.py)\n\n## 错误处理\n\nSchema 生成过程中可能遇到的错误及处理方式：\n\n| 错误类型 | 可能原因 | 解决方案 |\n|---------|---------|---------|\n| 请求失败 | API 密钥无效或网络问题 | 检查 API 密钥配置和网络连接 |\n| 超时错误 | 后端响应时间过长 | 稍后重试或减少 prompt 复杂度 |\n| 无效 Schema | 生成的 Schema 不符合规范 | 手动调整生成的 Schema 或简化 prompt |\n\n## 总结\n\nSchema 生成功能是 oxylabs AI Studio SDK 的一项强大特性，它通过自然语言处理技术自动将用户的数据提取需求转换为标准化的 JSON Schema。该功能显著降低了结构化数据提取的门槛，使开发者无需深入了解 JSON Schema 规范即可实现复杂的数据提取任务。\n\n通过配合使用 `generate_schema()` 方法和 SDK 的抓取/爬取功能，用户可以快速构建端到端的数据提取工作流，实现从网页内容到结构化数据的自动化转换。\n\n---\n\n---\n\n## Doramagic 踩坑日志\n\n项目：oxylabs/oxylabs-ai-studio-py\n\n摘要：发现 9 个潜在踩坑项，其中 0 个为 high/blocking；最高优先级：身份坑 - 仓库名和安装名不一致。\n\n## 1. 身份坑 · 仓库名和安装名不一致\n\n- 严重度：medium\n- 证据强度：runtime_trace\n- 发现：仓库名 `oxylabs-ai-studio-py` 与安装入口 `oxylabs-ai-studio` 不完全一致。\n- 对用户的影响：用户照着仓库名搜索包或照着包名找仓库时容易走错入口。\n- 建议检查：在 npm/PyPI/GitHub 上确认包名映射和官方 README 说明。\n- 复现命令：`pip install oxylabs-ai-studio`\n- 防护动作：页面必须同时展示 repo 名和真实安装入口，避免用户搜索错包。\n- 证据：identity.distribution | github_repo:1003630893 | https://github.com/oxylabs/oxylabs-ai-studio-py | repo=oxylabs-ai-studio-py; install=oxylabs-ai-studio\n\n## 2. 能力坑 · 能力判断依赖假设\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：README/documentation is current enough for a first validation pass.\n- 对用户的影响：假设不成立时，用户拿不到承诺的能力。\n- 建议检查：将假设转成下游验证清单。\n- 防护动作：假设必须转成验证项；没有验证结果前不能写成事实。\n- 证据：capability.assumptions | github_repo:1003630893 | https://github.com/oxylabs/oxylabs-ai-studio-py | README/documentation is current enough for a first validation pass.\n\n## 3. 维护坑 · 来源证据：v.0.2.19\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个维护/版本相关的待验证问题：v.0.2.19\n- 对用户的影响：可能影响升级、迁移或版本选择。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_96a2e22cbea94aac8c2788f763ce7c04 | https://github.com/oxylabs/oxylabs-ai-studio-py/releases/tag/v0.2.19 | 来源类型 github_release 暴露的待验证使用条件。\n\n## 4. 维护坑 · 维护活跃度未知\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：未记录 last_activity_observed。\n- 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。\n- 建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。\n- 防护动作：维护活跃度未知时，推荐强度不能标为高信任。\n- 证据：evidence.maintainer_signals | github_repo:1003630893 | https://github.com/oxylabs/oxylabs-ai-studio-py | last_activity_observed missing\n\n## 5. 安全/权限坑 · 下游验证发现风险项\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：下游已经要求复核，不能在页面中弱化。\n- 建议检查：进入安全/权限治理复核队列。\n- 防护动作：下游风险存在时必须保持 review/recommendation 降级。\n- 证据：downstream_validation.risk_items | github_repo:1003630893 | https://github.com/oxylabs/oxylabs-ai-studio-py | no_demo; severity=medium\n\n## 6. 安全/权限坑 · 存在安全注意事项\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：No sandbox install has been executed yet; downstream must verify before user use.\n- 对用户的影响：用户安装前需要知道权限边界和敏感操作。\n- 建议检查：转成明确权限清单和安全审查提示。\n- 防护动作：安全注意事项必须面向用户前置展示。\n- 证据：risks.safety_notes | github_repo:1003630893 | https://github.com/oxylabs/oxylabs-ai-studio-py | No sandbox install has been executed yet; downstream must verify before user use.\n\n## 7. 安全/权限坑 · 存在评分风险\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：风险会影响是否适合普通用户安装。\n- 建议检查：把风险写入边界卡，并确认是否需要人工复核。\n- 防护动作：评分风险必须进入边界卡，不能只作为内部分数。\n- 证据：risks.scoring_risks | github_repo:1003630893 | https://github.com/oxylabs/oxylabs-ai-studio-py | no_demo; severity=medium\n\n## 8. 维护坑 · issue/PR 响应质量未知\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：issue_or_pr_quality=unknown。\n- 对用户的影响：用户无法判断遇到问题后是否有人维护。\n- 建议检查：抽样最近 issue/PR，判断是否长期无人处理。\n- 防护动作：issue/PR 响应未知时，必须提示维护风险。\n- 证据：evidence.maintainer_signals | github_repo:1003630893 | https://github.com/oxylabs/oxylabs-ai-studio-py | issue_or_pr_quality=unknown\n\n## 9. 维护坑 · 发布节奏不明确\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：release_recency=unknown。\n- 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。\n- 建议检查：确认最近 release/tag 和 README 安装命令是否一致。\n- 防护动作：发布节奏未知或过期时，安装说明必须标注可能漂移。\n- 证据：evidence.maintainer_signals | github_repo:1003630893 | https://github.com/oxylabs/oxylabs-ai-studio-py | release_recency=unknown\n\n\n",
"summary": "DeepWiki/Human Wiki 完整输出，末尾追加 Discovery Agent 踩坑日志。",
"title": "Human Manual / 人类版说明书"
},
"pitfall_log": {
"asset_id": "pitfall_log",
"filename": "PITFALL_LOG.md",
"markdown": "# Pitfall Log / 踩坑日志\n\n项目：oxylabs/oxylabs-ai-studio-py\n\n摘要：发现 9 个潜在踩坑项，其中 0 个为 high/blocking；最高优先级：身份坑 - 仓库名和安装名不一致。\n\n## 1. 身份坑 · 仓库名和安装名不一致\n\n- 严重度：medium\n- 证据强度：runtime_trace\n- 发现：仓库名 `oxylabs-ai-studio-py` 与安装入口 `oxylabs-ai-studio` 不完全一致。\n- 对用户的影响：用户照着仓库名搜索包或照着包名找仓库时容易走错入口。\n- 建议检查：在 npm/PyPI/GitHub 上确认包名映射和官方 README 说明。\n- 复现命令：`pip install oxylabs-ai-studio`\n- 防护动作：页面必须同时展示 repo 名和真实安装入口，避免用户搜索错包。\n- 证据：identity.distribution | github_repo:1003630893 | https://github.com/oxylabs/oxylabs-ai-studio-py | repo=oxylabs-ai-studio-py; install=oxylabs-ai-studio\n\n## 2. 能力坑 · 能力判断依赖假设\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：README/documentation is current enough for a first validation pass.\n- 对用户的影响：假设不成立时，用户拿不到承诺的能力。\n- 建议检查：将假设转成下游验证清单。\n- 防护动作：假设必须转成验证项；没有验证结果前不能写成事实。\n- 证据：capability.assumptions | github_repo:1003630893 | https://github.com/oxylabs/oxylabs-ai-studio-py | README/documentation is current enough for a first validation pass.\n\n## 3. 维护坑 · 来源证据：v.0.2.19\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个维护/版本相关的待验证问题：v.0.2.19\n- 对用户的影响：可能影响升级、迁移或版本选择。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_96a2e22cbea94aac8c2788f763ce7c04 | https://github.com/oxylabs/oxylabs-ai-studio-py/releases/tag/v0.2.19 | 来源类型 github_release 暴露的待验证使用条件。\n\n## 4. 维护坑 · 维护活跃度未知\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：未记录 last_activity_observed。\n- 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。\n- 建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。\n- 防护动作：维护活跃度未知时，推荐强度不能标为高信任。\n- 证据：evidence.maintainer_signals | github_repo:1003630893 | https://github.com/oxylabs/oxylabs-ai-studio-py | last_activity_observed missing\n\n## 5. 安全/权限坑 · 下游验证发现风险项\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：下游已经要求复核，不能在页面中弱化。\n- 建议检查：进入安全/权限治理复核队列。\n- 防护动作：下游风险存在时必须保持 review/recommendation 降级。\n- 证据：downstream_validation.risk_items | github_repo:1003630893 | https://github.com/oxylabs/oxylabs-ai-studio-py | no_demo; severity=medium\n\n## 6. 安全/权限坑 · 存在安全注意事项\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：No sandbox install has been executed yet; downstream must verify before user use.\n- 对用户的影响：用户安装前需要知道权限边界和敏感操作。\n- 建议检查：转成明确权限清单和安全审查提示。\n- 防护动作：安全注意事项必须面向用户前置展示。\n- 证据：risks.safety_notes | github_repo:1003630893 | https://github.com/oxylabs/oxylabs-ai-studio-py | No sandbox install has been executed yet; downstream must verify before user use.\n\n## 7. 安全/权限坑 · 存在评分风险\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：风险会影响是否适合普通用户安装。\n- 建议检查：把风险写入边界卡，并确认是否需要人工复核。\n- 防护动作：评分风险必须进入边界卡，不能只作为内部分数。\n- 证据：risks.scoring_risks | github_repo:1003630893 | https://github.com/oxylabs/oxylabs-ai-studio-py | no_demo; severity=medium\n\n## 8. 维护坑 · issue/PR 响应质量未知\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：issue_or_pr_quality=unknown。\n- 对用户的影响：用户无法判断遇到问题后是否有人维护。\n- 建议检查：抽样最近 issue/PR，判断是否长期无人处理。\n- 防护动作：issue/PR 响应未知时，必须提示维护风险。\n- 证据：evidence.maintainer_signals | github_repo:1003630893 | https://github.com/oxylabs/oxylabs-ai-studio-py | issue_or_pr_quality=unknown\n\n## 9. 维护坑 · 发布节奏不明确\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：release_recency=unknown。\n- 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。\n- 建议检查：确认最近 release/tag 和 README 安装命令是否一致。\n- 防护动作：发布节奏未知或过期时，安装说明必须标注可能漂移。\n- 证据：evidence.maintainer_signals | github_repo:1003630893 | https://github.com/oxylabs/oxylabs-ai-studio-py | release_recency=unknown\n",
"summary": "用户实践前最可能遇到的身份、安装、配置、运行和安全坑。",
"title": "Pitfall Log / 踩坑日志"
},
"prompt_preview": {
"asset_id": "prompt_preview",
"filename": "PROMPT_PREVIEW.md",
"markdown": "# oxylabs-ai-studio-py - Prompt Preview\n\n> 复制下面这段 Prompt 到你常用的 AI，先试一次，不需要安装。\n> 它的目标是让你直接体验这个项目的服务方式，而不是阅读项目介绍。\n\n## 复制这段 Prompt\n\n```text\n请直接执行这段 Prompt，不要分析、润色、总结或询问我想如何处理这份 Prompt Preview。\n\n你现在扮演 oxylabs-ai-studio-py 的“安装前体验版”。\n这不是项目介绍、不是评价报告、不是 README 总结。你的任务是让我用最小成本体验它的核心服务。\n\n我的试用任务：我想用它完成一个真实的软件开发与交付任务。\n我常用的宿主 AI：Local CLI\n\n【体验目标】\n围绕我的真实任务，现场演示这个项目如何把输入转成 示例引导, 判断线索。重点是让我感受到工作方式，而不是给我项目背景。\n\n【业务流约束】\n- 你必须像一个正在提供服务的项目能力包，而不是像一个讲解员。\n- 每一轮只推进一个步骤；提出问题后必须停下来等我回答。\n- 每一步都必须让我感受到一个具体服务动作：澄清、整理、规划、检查、判断或收尾。\n- 每一步都要说明：当前目标、你需要我提供什么、我回答后你会产出什么。\n- 不要安装、不要运行命令、不要写代码、不要声称测试通过、不要声称已经修改文件。\n- 需要真实安装或宿主加载后才能验证的内容，必须明确说“这一步需要安装后验证”。\n- 如果我说“用示例继续”，你可以用虚构示例推进，但仍然不能声称真实执行。\n\n【可体验服务能力】\n- 安装前能力预览: Structured data gathering from any website using AI-powered scraper, crawler, and browser automation. Scraping and crawling with natural language prompts. Equip your LLM agents with fresh data. AI Studio python SDK for intelligent web data gathering. 输入：用户任务, 当前 AI 对话上下文；输出：示例引导, 判断线索。\n\n【必须安装后才可验证的能力】\n- 命令行启动或安装流程: 项目文档中存在可执行命令，真实使用需要在本地或宿主环境中运行这些命令。 输入：终端环境, 包管理器, 项目依赖；输出：安装结果, 列表/更新/运行结果。\n\n【核心服务流】\n请严格按这个顺序带我体验。不要一次性输出完整流程：\n1. introduction：项目介绍。围绕“项目介绍”模拟一次用户任务，不展示安装或运行结果。\n2. quick-start：快速入门。围绕“快速入门”模拟一次用户任务，不展示安装或运行结果。\n3. ai-scraper：AI-Scraper 文档。围绕“AI-Scraper 文档”模拟一次用户任务，不展示安装或运行结果。\n4. ai-crawler：AI-Crawler 文档。围绕“AI-Crawler 文档”模拟一次用户任务，不展示安装或运行结果。\n5. api-client：API 客户端架构。围绕“API 客户端架构”模拟一次用户任务，不展示安装或运行结果。\n\n【核心能力体验剧本】\n每一步都必须按“输入 -> 服务动作 -> 中间产物”执行。不要只说流程名：\n1. introduction\n输入：用户提供的“项目介绍”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n2. quick-start\n输入：用户提供的“快速入门”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n3. ai-scraper\n输入：用户提供的“AI-Scraper 文档”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n4. ai-crawler\n输入：用户提供的“AI-Crawler 文档”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n5. api-client\n输入：用户提供的“API 客户端架构”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n【项目服务规则】\n这些规则决定你如何服务用户。不要解释规则本身，而要在每一步执行时遵守：\n- 先确认用户任务、输入材料和成功标准，再模拟项目能力。\n- 每一步都必须形成可检查的小产物，并等待用户确认后再继续。\n- 凡是需要安装、调用工具或访问外部服务的能力，都必须标记为安装后验证。\n\n【每一步的服务约束】\n- Step 1 / introduction：Step 1 必须围绕“项目介绍”形成一个小中间产物，并等待用户确认。\n- Step 2 / quick-start：Step 2 必须围绕“快速入门”形成一个小中间产物，并等待用户确认。\n- Step 3 / ai-scraper：Step 3 必须围绕“AI-Scraper 文档”形成一个小中间产物，并等待用户确认。\n- Step 4 / ai-crawler：Step 4 必须围绕“AI-Crawler 文档”形成一个小中间产物，并等待用户确认。\n- Step 5 / api-client：Step 5 必须围绕“API 客户端架构”形成一个小中间产物，并等待用户确认。\n\n【边界与风险】\n- 不要声称已经安装、运行、调用 API、读写本地文件或完成真实任务。\n- 安装前预览只能展示工作方式，不能证明兼容性、性能或输出质量。\n- 涉及安装、插件加载、工具调用或外部服务的能力必须安装后验证。\n\n【可追溯依据】\n这些路径只用于你内部校验或在我追问“依据是什么”时简要引用。不要在首次回复主动展开：\n- https://github.com/oxylabs/oxylabs-ai-studio-py\n- https://github.com/oxylabs/oxylabs-ai-studio-py#readme\n- readme.md\n- pyproject.toml\n- src/oxylabs_ai_studio/settings.py\n- src/oxylabs_ai_studio/__init__.py\n- src/oxylabs_ai_studio/apps/ai_scraper.py\n- examples/scrape_markdown.py\n- examples/scrape_pydantic_schema.py\n- examples/scrape_generated_schema.py\n- src/oxylabs_ai_studio/apps/ai_crawler.py\n- examples/crawl_markdown.py\n\n【首次问题规则】\n- 首次三问必须先确认用户目标、成功标准和边界，不要提前进入工具、安装或实现细节。\n- 如果后续需要技术条件、文件路径或运行环境，必须等用户确认目标后再追问。\n\n首次回复必须只输出下面 4 个部分：\n1. 体验开始：用 1 句话说明你将带我体验 oxylabs-ai-studio-py 的核心服务。\n2. 当前步骤：明确进入 Step 1，并说明这一步要解决什么。\n3. 你会如何服务我：说明你会先改变我完成任务的哪个动作。\n4. 只问我 3 个问题，然后停下等待回答。\n\n首次回复禁止输出：后续完整流程、证据清单、安装命令、项目评价、营销文案、已经安装或运行的说法。\n\nStep 1 / brainstorming 的二轮协议：\n- 我回答首次三问后，你仍然停留在 Step 1 / brainstorming，不要进入 Step 2。\n- 第二次回复必须产出 6 个部分：澄清后的任务定义、成功标准、边界条件、\n 2-3 个可选方案、每个方案的权衡、推荐方案。\n- 第二次回复最后必须问我是否确认推荐方案；只有我明确确认后，才能进入下一步。\n- 第二次回复禁止输出 git worktree、代码计划、测试文件、命令或真实执行结果。\n\n后续对话规则：\n- 我回答后，你先完成当前步骤的中间产物并等待确认；只有我确认后，才能进入下一步。\n- 每一步都要生成一个小的中间产物，例如澄清后的目标、计划草案、测试意图、验证清单或继续/停止判断。\n- 所有演示都写成“我会建议/我会引导/这一步会形成”，不要写成已经真实执行。\n- 不要声称已经测试通过、文件已修改、命令已运行或结果已产生。\n- 如果某个能力必须安装后验证，请直接说“这一步需要安装后验证”。\n- 如果证据不足，请明确说“证据不足”，不要补事实。\n```\n",
"summary": "不安装项目也能感受能力节奏的安全试用 Prompt。",
"title": "Prompt Preview / 安装前试用 Prompt"
},
"quick_start": {
"asset_id": "quick_start",
"filename": "QUICK_START.md",
"markdown": "# Quick Start / 官方入口\n\n项目：oxylabs/oxylabs-ai-studio-py\n\n## 官方安装入口\n\n### Python / pip · 官方安装入口\n\n```bash\npip install oxylabs-ai-studio\n```\n\n来源：https://github.com/oxylabs/oxylabs-ai-studio-py#readme\n\n## 来源\n\n- repo: https://github.com/oxylabs/oxylabs-ai-studio-py\n- docs: https://github.com/oxylabs/oxylabs-ai-studio-py#readme\n",
"summary": "从项目官方 README 或安装文档提取的开工入口。",
"title": "Quick Start / 官方入口"
}
},
"validation_id": "dval_79126fc4f2384013954c78fe80c83a06"
}