tierproxy

tierproxy — Python SDK

🚧 预览版。 网关尚未正式推出。请发送邮件至 [email protected] 加入 等候名单。SDK 功能可用，但通过 tierproxy doctor 检查在线网关需要邀请。

面向 AI/ML 流水线的高端多服务商代理基础设施。专为反复衡量成本、延迟和成功率，并使用 Python 编写代码的工程师打造。

安装

pip install tierproxy

快速入门 — 五秒上手

import tierproxy
r = tierproxy.get("https://example.com", country="US")
print(r.text)

就这么简单。（请先设置 TIERPROXY_API_KEY 环境变量。）

三行代码，持久会话

from tierproxy import TierProxy
with TierProxy() as g:
    print(g.me.get().client_id)
    r = g.get("https://example.com", country="US", session_id="s1")

每次请求自动选择最便宜且健康的上游

g = TierProxy(routing="cheapest")  # also: "fastest", "most_reliable", "balanced"
g.get("https://example.com")     # picks via /v1/health/upstreams under the hood

成本保护措施

g = TierProxy(
    monthly_budget_usd=200.0,    # raises BudgetExceededError before going over
)

高级选项

import httpx
from tierproxy import TierProxy
from tierproxy.retry import RetryPolicy

g = TierProxy(
    api_key="tp_live_...",
    base_url="https://my-self-hosted-gw:8444",
    timeout=10.0,
    retry_policy=RetryPolicy(max_retries=5, retry_on_status=frozenset({500, 502})),
    http_client=httpx.Client(verify=False),  # custom transport
    user_agent_suffix="my-app/2.3",          # attribution
)

原始模式（Playwright、curl 等）

from tierproxy import ProxyURL

p = ProxyURL(api_key="tp_live_...", country="US", mode="username_encoding")
print(p.http_url())  # http://customer-tp_live_...-cc-US:[email protected]:443

错误处理

所有 SDK 错误都继承自 tierproxy.TierProxyError，并包含用于升级支持请求的 request_id：

from tierproxy import TierProxy, RateLimitError
import time

with TierProxy() as g:
    try:
        resp = g.get("https://example.com/page")
    except RateLimitError as e:
        time.sleep(e.retry_after or 5)
        resp = g.get("https://example.com/page")

完整的 HTTP 状态码与异常映射，请参阅错误参考。

AI Agent 集成

SDK 会将响应模型公开为 JSON Schema，并提供适用于 Anthropic Claude 和 OpenAI 函数调用的预构建工具定义：

import anthropic
from tierproxy import TierProxy, schemas

with TierProxy() as gw:
    anthropic.Anthropic().messages.create(
        model="claude-sonnet-4-6",
        max_tokens=1024,
        tools=schemas.anthropic_tools(),
        messages=[{"role": "user", "content": "How much quota is left?"}],
    )

请参阅 AI 集成指南 和 MCP 服务文档 examples/mcp_claude_desktop.md。

tierproxy 对比

	tierproxy	Smartproxy SDK	Bright Data SDK	Oxylabs SDK	DataImpulse
多服务商路由	✅	❌	❌	❌	❌
客户端智能选择器（考虑成本）	✅	❌	❌	❌	❌
实时使用量流式传输（SSE）	✅	❌	❌	❌	❌
MCP 服务（Claude/Cursor/Cline）	✅	❌	❌	❌	❌
内置 OpenTelemetry	✅	❌	❌	❌	❌
同步与异步功能一致	✅	部分	部分	部分	部分
随附的 AI/ML 框架示例	8	0	1	0	0
类型安全（Pydantic v2 + mypy strict）	✅	❌	❌	部分	❌
OpenAPI 3.1 规范	✅	❌	❌	❌	❌
可通过 Pip 安装的 CLI（tierproxy doctor）	✅	❌	❌	❌	❌
按请求归因成本（惰性）	✅	❌	❌	❌	❌
JA3/JA4 TLS 指纹轮换	✅	❌	❌	❌	❌
速率限制学习 + 自动故障转移	✅	❌	❌	❌	❌
许可证	Apache 2.0	专有	专有	专有	专有

功能

• 五秒快速入门 — import tierproxy; tierproxy.get(url, country="US")
• 分层 API — 提供从单行代码到高级用户可调参数的五个集成级别
• 智能路由 — routing="cheapest" 会为每个请求自动选择健康的上游服务
• 费用控制 — monthly_budget_usd= 会拒绝超出预算的请求
• 按请求归因费用 — client.cost_for(resp) 返回 USD；使用延迟加载的 30s 缓存，不增加单次请求开销
• 客户端响应缓存 — cache_ttl=300, cache_max_response_size=262144，带大小上限的 LRU 缓存
• 多提供商自动故障切换 — auto_failover=True 会在遇到 429/5xx 时重试下一个最优上游服务
• 速率限制学习 — client.rate_limits.get() 展示按目标域名聚合的网关 429 错误
• JA3/JA4 TLS 轮换 — 按上游服务随机轮换指纹（网关端；参见 TLS 指纹指南）
• Cookie 持久化 — 在多步骤抓取过程中，Cookie 会关联到 session_id
• 流式响应 — client.get(url, stream=True) 返回迭代器（适用于大文件、SSE）
• 实时 SSE 流 — for delta in g.usage.stream() 可持续获取本月至今的字节数
• MCP 服务 — tierproxy-mcp 将代理作为工具提供给 Claude/Cursor/Cline
• 8 种框架集成 — LangChain、LlamaIndex、Crawl4AI、Playwright、Firecrawl、Browser-Use、CrewAI
• 可选启用 OpenTelemetry — 使用 pip install tierproxy[otel] 进行分布式追踪
• 地理位置 + 粘性会话 — 支持国家、城市，以及 1-1440min 的会话固定时长
• 双 URL 语法 — 支持标头（httpx/requests）和用户名编码（Playwright）
• 端到端类型安全 — Pydantic v2 模型、严格 mypy 检查、完整的 IDE 自动补全

参见 examples/ 中的 LangChain/LlamaIndex/Crawl4AI/Playwright 示例，以及 examples/levels.py 中可运行的各级别演示。

与你喜爱的 AI/Agent 框架配合使用

框架	示例	说明
LangChain	with_langchain.py	通过代理使用 RAG 文档加载器
LlamaIndex	with_llamaindex.py	通过代理使用 SimpleWebPageReader
Crawl4AI	with_crawl4ai.py	Playwright 爬虫 + tierproxy
Firecrawl（热门）	with_firecrawl.py	可自托管的 Firecrawl + 住宅 IP
Browser-Use（热门）	with_browser_use.py	由大模型驱动的自主浏览器
CrewAI（热门）	with_crewai.py	多 Agent 抓取团队 + 费用感知路由
Playwright	with_playwright.py	通过 tierproxy 直接使用 Playwright
MCP（Claude/Cursor/Cline/Windsurf）（独有）	mcp_claude_desktop.md	通过 tierproxy-mcp 实现原生工具集成

MCP 服务（Claude Desktop / Cursor / Cline / Windsurf）

pip install tierproxy[mcp]

然后添加到 MCP 客户端配置中：

{
  "mcpServers": {
    "tierproxy": {
      "command": "tierproxy-mcp",
      "env": { "TIERPROXY_API_KEY": "tp_live_..." }
    }
  }
}

现在，你的 AI 助手可以调用 fetch_url(url, country="US")，检查健康状态和用量，并通过最便宜的健康上游服务进行路由——无需编写胶水代码，无需导入 httpx，也无需编写样板代码。