IPIPAI 开源 SDK 正式发布 — 让 AI 大模型一键接入 IP 情报查询

引言：一次调用，获取完整 IP 画像

IPIPAI MCP（Model Context Protocol）层是专为 AI Agent 和大语言模型设计的网络情报 API。传统 IP 查询工具返回零散的地理信息，需要 Agent 自行拼接多个 API 才能得出判断。MCP 层把这一切压缩成一次 HTTP 请求：IP 检测、风险评分、AI 服务可用性、流媒体解锁、网络质量，全部在一个结构化 JSON 响应中返回。

过去，要让一个大模型判断"某个 IP 能不能访问 ChatGPT"，开发者需要分别调用 IP 地理定位 API、代理检测 API、风险评分 API、再到目标服务做连通性测试，最后自己写一套规则把结果拼起来。这套流程不仅消耗大量 token，还容易出现推理错误。IPIPAI MCP 层将这些步骤全部收敛到服务端，客户端 SDK 只需要三行代码就能拿到一个带有 ipai_score（0-100 分）和等级（A+ 到 D）的结构化结果。

大模型不再需要理解复杂的 IP 检测逻辑。SDK 返回的 JSON 包含一个 ipai_score 字段和对应的等级，Agent 只需读取这个数字就能给出判断。这大幅降低了 LLM 调用工具的 token 消耗和推理成本，也让回答变得有数据支撑、可解释、可追溯。

本文将全面介绍 @ipipai/sdk 的设计理念、安装方式、七个 API 方法、五维评分算法、大模型接入指南，以及 IPIPAI 最新集成的 OpenIPAPI 第三方数据源。无论你是 AI Agent 开发者、跨境电商运营者，还是代理节点筛选从业者，都能从中找到直接可用的接入方案。

开源 SDK 特性：@ipipai/sdk

@ipipai/sdk 是 IPIPAI 官方 JavaScript/TypeScript SDK，以 MIT 许可证开源。它是一个"瘦"HTTP 客户端，只封装 API 调用，不包含任何算法逻辑——评分引擎、风险模型、MMDB 数据库全部在服务端闭源运行。这种架构保证了客户端极小体积的同时，服务端可以持续升级算法而无需用户更新 SDK。

SDK 在设计上遵循三个原则：极简、类型安全、零依赖。下面逐一介绍核心特性。

三格式构建

SDK 同时输出三种模块格式，覆盖所有 JavaScript 运行环境：

• CommonJS（.js） — 适配传统 Node.js 项目，通过 require() 引入，兼容 Express、Koa 等服务端框架。
• ESM（.mjs） — 适配现代打包工具（Vite、esbuild、Rollup）和原生 ESM 环境（Deno、Node.js ESM 模式），支持 Tree-shaking。
• UMD（.min.js） — 适配浏览器直接 <script> 引入场景，无需构建工具，挂载到全局 window.IPIPAIClient。

无论你的项目用什么技术栈，都能找到对应的引入方式。package.json 的 exports 字段做了完整的条件导出映射，Node.js 和打包工具会自动选择最合适的格式。

TypeScript 原生

SDK 使用 TypeScript 编写，构建产物中包含完整的 .d.ts 类型定义文件。所有请求参数和响应结构都有精确的类型标注，IDE（VS Code、WebStorm）可以提供完整的自动补全和类型检查。

这意味着你不需要额外安装 @types/ipipai__sdk 这样的类型补充包——类型定义已经内置在主包中。从初始化客户端到读取响应字段，每一步都有类型提示，避免拼写错误和字段误用。

零运行时依赖

SDK 构建产物压缩后仅约 4KB，不依赖 axios、node-fetch、got 或任何第三方 HTTP 库。它直接使用原生 fetch API（Node.js 18+ 和所有现代浏览器均已内置），这意味着：

• 安装后不会在 node_modules 中引入额外依赖，不会产生依赖冲突。
• 供应链安全风险降到最低——你的项目中不会因为 SDK 而多出几十个传递依赖。
• 在 Deno、Bun、Cloudflare Workers、Vercel Edge Functions 等 Edge 运行时中也能直接运行。

如果你的项目运行在不支持原生 fetch 的旧版 Node.js（16 及以下），只需额外安装 undici 并在入口处 polyfill 即可。

中英双语

所有 API 响应支持 lang: 'zh' 和 lang: 'en' 切换。评分评语（如"优秀 — 高度适合 AI 工作流"）、风险等级描述（如"非常安全"、"中等风险"）、AI 服务不可用原因说明等文本字段会根据 lang 参数自动本地化。

这使得同一个 SDK 既可以服务于中文用户场景（如国内的 AI Agent），也可以服务于国际化产品。Agent 可以根据用户提问的语言自动选择对应的 lang，确保返回的自然语言描述与对话上下文一致。

安装与快速开始

SDK 已发布到 npm 官方仓库，支持 npm、yarn、pnpm 等所有主流包管理器安装。安装过程不需要任何全局依赖或编译步骤。

安装

# npm
npm install @ipipai/sdk

# yarn
yarn add @ipipai/sdk

# pnpm
pnpm add @ipipai/sdk

三行代码开始

安装完成后，只需三行代码即可完成一次完整的 IP 情报查询：

const { IPIPAIClient } = require('@ipipai/sdk');

const client = new IPIPAIClient({ apiKey: 'your-api-key', lang: 'zh' });

const result = await client.analyze('8.8.8.8', { checkServices: true });
console.log(result.ipai_score, result.grade);  // 96 A+

第一行引入 SDK 的 IPIPAIClient 类；第二行用你的 API Key 初始化客户端（lang: 'zh' 表示返回中文描述）；第三行调用 analyze 方法查询 8.8.8.8 的完整画像，checkServices: true 表示同时检测 AI 服务和流媒体可用性。

返回的 result 对象包含评分、等级、IP 身份信息、风险评级、AI 服务可用性、流媒体解锁状态、网络质量指标等全部字段。Agent 只需读取 result.ipai_score 和 result.recommendation 就能用自然语言回答用户。

ESM 引入方式

如果你使用 ES Module 或 TypeScript，推荐使用 import 语法：

import { IPIPAIClient } from '@ipipai/sdk';
import type { AnalyzeResponse } from '@ipipai/sdk';

const client = new IPIPAIClient({ apiKey: process.env.IPIPAI_API_KEY });
const result: AnalyzeResponse = await client.analyze('1.1.1.1');

注意 import type 语法只引入类型定义，不会增加运行时体积。在 tsconfig.json 中开启 verbatimModuleSyntax: true 可以确保类型导入在编译时被正确擦除。

IPIPAI Score 五维评分算法

IPIPAI Score 是专有的 AI 统一智能评分（AI Unified Intelligence Score），满分 100 分，由五个维度加权计算得出。它不是简单的 IP 黑名单查询，而是一个融合了 IP 纯净度、AI 可用性、网络质量、稳定性和安全性的综合评估模型。

这个评分的设计目标是为 AI Agent 提供一个"一句话就能理解"的指标。与其让大模型阅读十几页 JSON 字段再自行推理，不如直接给出一个 0-100 的数字和 A+ 到 D 的等级——Agent 读取这一个数字就能做出判断，大幅节省 token 和推理时间。

五维权重分布

下表详细解释了每个维度的计算依据和权重：

维度	权重	评估内容
IP 纯净度	30%	检测 IP 是否为已知代理出口、Tor 节点、VPN 节点，是否出现在主流威胁情报黑名单中。住宅原生 IP 得分最高，数据中心 IP 次之，已知代理/Tor 得分最低。
AI 可用性	25%	检测 ChatGPT、Claude、Gemini、Copilot 四大 AI 服务是否可从该 IP 正常访问。综合考虑地理位置封锁、Cloudflare 风控拦截、OpenAI 地区限制等因素。
网络质量	20%	评估 IP 的网络带宽、延迟、丢包率和连接稳定性。通过多节点探测和历史数据综合计算，反映 IP 的实际传输性能。
稳定性	15%	评估 IP 类型（住宅/商业/数据中心）和原生状态。原生住宅 IP 稳定性最高，频繁更换的动态 IP 和共享代理稳定性较低。
安全性	10%	综合风险分和黑名单状态，评估 IP 是否曾参与恶意活动（垃圾邮件、暴力破解、DDoS 等），是否被安全厂商标记为高风险。

等级量表

评分对应六个等级，Agent 可以直接将等级映射为自然语言建议：

分数区间	等级	含义
90 - 100	A+	优秀 — 高度适合 AI 工作流
80 - 89	A	良好 — 适合 AI 和流媒体
70 - 79	B+	中上 — 可用但可能受限
60 - 69	B	中等 — 部分服务可能不可用
50 - 59	C	较差 — 经常被封，不建议用于 AI
0 - 49	D	差 — 高风险被封禁

七个 API 方法

SDK 提供七个方法，从工具发现到综合评级，从单 IP 检测到批量筛查，覆盖 IP 情报查询的全部需求。每个方法都对应一个 HTTP 端点，返回结构化的 JSON 响应。

方法	HTTP	端点	用途
discovery()	GET	/api/v2/discovery	列出所有 MCP 工具与参数定义，供 Agent 自动发现
analyze(ip, opts)	POST	/api/v2/analyze	统一网络情报分析（核心工具），返回完整 IP 画像
reputation(ip, opts)	GET	/api/v2/reputation/:ip	快速 IP 信誉检查，检测代理/Tor/黑名单状态
serviceAccess(ip, svc, opts)	GET	/api/v2/access/:ip/:service	检测特定服务可访问性（如 chatgpt、netflix）
rateNode(ip, opts)	POST	/api/v2/rate	VPS/代理/数据中心 IP 综合评级，输出五维星级
score(ip)	—	调用 analyze	便捷方法：只取评分数字和等级
isSafeForAI(ip)	—	调用 analyze	便捷方法：返回布尔值，判断是否适合 AI 使用

方法详解

discovery()

这是 AI Agent 自动发现工具的入口。调用后返回一个 JSON 清单，列出所有可用工具的名称、描述、参数定义和返回格式。Agent 读取这个清单后，可以自主决定调用哪个工具、传什么参数，无需开发者硬编码。

const tools = await client.discovery();
// tools 包含每个方法的 schema 定义
// Agent 可据此自动编排调用链

analyze(ip, opts)

核心方法，一次调用返回 IP 的完整画像。可选参数 checkServices 控制是否检测 AI 服务和流媒体可用性，lang 控制返回语言。这是绝大多数场景下应该使用的方法。

const result = await client.analyze('8.8.8.8', {
  checkServices: true,
  lang: 'zh'
});
// result.ipai_score, result.grade, result.ai, result.risk ...

reputation(ip, opts)

轻量级信誉查询，只返回 IP 的风险评级和代理/Tor/黑名单状态，不包含完整分析。适合需要快速过滤大批 IP 的场景，响应体积小、速度快。

const rep = await client.reputation('1.2.3.4');
// rep.score, rep.level, rep.proxy, rep.tor, rep.hosting

serviceAccess(ip, svc, opts)

针对单个服务的可用性检测。传入 IP 和服务名（如 chatgpt、netflix），返回该服务是否可从该 IP 访问。适合只需要判断单一服务的场景。

const access = await client.serviceAccess('8.8.8.8', 'chatgpt');
// access.accessible => true / false
// access.note => "ok" 或不可用原因

rateNode(ip, opts)

专为 VPS、代理节点、数据中心 IP 设计的综合评级方法。输出五维星级评定（纯净度、AI 可用性、网络质量、稳定性、安全性各 1-5 星），适合代理节点筛选和批量评测场景。

score(ip) 与 isSafeForAI(ip)

这两个是便捷方法，内部都调用 analyze，但只提取你需要的那部分结果。score(ip) 只返回评分数字和等级，isSafeForAI(ip) 只返回一个布尔值。适合 Agent 在推理链中需要快速判断的场景。

const { score, grade } = await client.score('8.8.8.8');
// score => 96, grade => 'A+'

const safe = await client.isSafeForAI('1.2.3.4');
// safe => true / false

支持检测的服务

SDK 目前支持检测 12 个主流服务的可访问性，覆盖 AI 工具、流媒体平台和常用互联网服务。服务可用性基于 IP 地理位置和区域封锁策略综合推断。

AI 服务（蓝色标签）

四大 AI 服务的检测逻辑各有不同：ChatGPT 主要受 OpenAI 的地区限制政策影响；Claude（Anthropic）有类似的地区限制；Gemini 受 Google 服务区域策略约束；Copilot 受 Microsoft 区域策略约束。IPIPAI 会综合 Cloudflare 风控拦截、API 端点可达性、地区限制状态来判断每个服务的实际可用性。

流媒体服务（绿色标签）

流媒体解锁检测通过模拟各平台的区域检测接口实现。Netflix 检测包括是否解锁原创内容、是否仅解锁自制剧；Disney+ 检测区域可用性；YouTube 检测 Premium 区域限制；Spotify 检测音频可用区域；TikTok 检测地区版本。

其他服务

这三个服务用于判断 IP 是否被主流互联网平台正常接受。Google 检测搜索和账号登录可用性；GitHub 检测 Git 操作和 Web 访问；Twitter（X）检测 API 和 Web 访问。如果这三个基础服务都不可用，通常意味着 IP 存在严重的信誉问题。

大模型接入指南

IPIPAI MCP 层的核心理念是：大模型不应该猜测一个 IP 是否安全，而应该查询。通过 SDK，AI Agent 可以在对话中实时获取 IP 评分、AI 服务可用性和风险评级，给出有数据支撑的回答。

接入方式不限于 JavaScript SDK。由于底层是标准 HTTP API，任何能发 HTTP 请求的编程语言都可以接入。下面给出 Python、cURL 和 Agent 工作流三种典型接入示例。

Python 接入示例

Python 是 AI Agent 开发最常用的语言。使用标准库 requests 即可完成接入，无需额外 SDK：

import requests

# 查询 IP 的 IPIPAI 评分
resp = requests.post(
    "https://ipipai.com/api/v2/analyze",
    json={"ip": "8.8.8.8", "check_services": True, "lang": "zh"},
    headers={"X-API-Key": "your-api-key"}
)
data = resp.json()

print(f"评分: {data['ipai_score']}/100 ({data['grade']})")
print(f"ChatGPT: {data['ai']['chatgpt']['accessible']}")
print(f"建议: {data['recommendation']}")
# 评分: 96/100 (A+)
# ChatGPT: True
# 建议: 优秀 — 非常适合AI工作流

在 LangChain 或 LlamaIndex 等框架中，可以将这段代码封装为一个 Tool，让 Agent 在需要 IP 情报时自动调用。关键是将返回的 JSON 结构设计得对 LLM 友好——IPIPAI 的响应已经做了这一点，recommendation 字段直接给出中文建议，Agent 可以原样转述。

cURL 一行命令

对于快速测试或 Shell 脚本场景，可以直接用 cURL 调用 API：

curl -X POST https://ipipai.com/api/v2/analyze \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your-api-key" \
  -d '{"ip":"8.8.8.8","check_services":true,"lang":"zh"}'

返回的 JSON 可以通过 jq 工具提取特定字段，例如只取评分：

curl -s -X POST https://ipipai.com/api/v2/analyze \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your-api-key" \
  -d '{"ip":"8.8.8.8"}' | jq '.ipai_score'
# 输出: 96

Agent 工作流示例

当用户问"这个 IP 能用 ChatGPT 吗？"时，Agent 的处理流程如下：

// 1. Agent 接收到用户问题："1.2.3.4 这个 IP 能用 ChatGPT 吗？"

// 2. Agent 调用 IPIPAI SDK
const result = await client.analyze('1.2.3.4', {
  checkServices: true,
  lang: 'zh'
});

// 3. Agent 读取结构化结果
console.log(result.ai.chatgpt.accessible);  // true / false
console.log(result.ipai_score);              // 96
console.log(result.recommendation);          // "优秀 — 非常适合AI工作流"

// 4. Agent 用自然语言回答用户
// "1.2.3.4 的 IPIPAI 评分为 96 分（A+），
//  ChatGPT 可正常访问，该 IP 非常适合 AI 工作流。"

整个流程中，Agent 不需要理解 IP 检测的技术细节——它只需要知道"有一个叫 analyze 的工具，传入 IP 就能拿到结果"。这正是 MCP 协议的设计目标：让工具调用像函数调用一样简单。

响应示例

以下是 analyze 方法返回的完整 JSON 结构（以 8.8.8.8 为例）：

{
  "ipai_score": 96,
  "grade": "A+",
  "identity": {
    "ip": "8.8.8.8",
    "type": "datacenter",
    "asn": "AS15169 Google LLC",
    "country": "United States",
    "isp": "Google LLC",
    "native": true
  },
  "risk": {
    "score": 12,
    "level": "非常安全",
    "proxy": false,
    "tor": false,
    "hosting": true
  },
  "ai": {
    "chatgpt": { "accessible": true, "note": "ok" },
    "claude":  { "accessible": true, "note": "ok" },
    "gemini":  { "accessible": true, "note": "ok" },
    "copilot": { "accessible": true, "note": "ok" }
  },
  "score_dimensions": {
    "purity": 30,
    "ai_availability": 25,
    "network_quality": 20,
    "stability": 14,
    "security": 9
  },
  "recommendation": "优秀 — 非常适合AI工作流",
  "_engine": "IPIPAI MCP v1.0"
}

其中 score_dimensions 字段展示了五个维度各自的得分，方便开发者做更细粒度的分析。例如，如果一个 IP 总分不高但 ai_availability 满分，说明它虽然整体质量一般，但用于访问 AI 服务没问题。

OpenIPAPI 数据源集成

为了提供更精准的 IP 地理位置信息，IPIPAI 集成了 OpenIPAPI 作为第三方 IP 位置查询数据源。OpenIPAPI 是一个开源的 IP 地理位置查询项目，提供简洁的 RESTful API 接口，接入简单，只需一个 GET 请求即可获取 IP 的地理位置、运营商、ASN 等信息。

项目介绍

OpenIPAPI 的项目介绍页托管在 GitHub 上，包含完整的项目说明、数据来源、更新频率和使用文档。作为一个开源项目，它的数据由社区维护和校验，覆盖全球 IP 段的地理位置信息。

API 端点与请求方式

属性	值
API 端点	https://openipapi.cloudshield.club/api
请求方法	GET
必填参数	ip（要查询的 IP 地址）
认证	无需 API Key，公开接口
返回格式	JSON

使用示例

OpenIPAPI 的接入极为简单，只需一个 GET 请求，无需任何认证头或请求体：

curl "https://openipapi.cloudshield.club/api?ip=1.1.1.1"

在 Python 中同样简单：

import requests

resp = requests.get("https://openipapi.cloudshield.club/api", params={"ip": "1.1.1.1"})
data = resp.json()
print(data)

返回示例

以下是查询 1.1.1.1 时返回的 JSON 示例：

{
  "ip": "1.1.1.1",
  "country": "Australia",
  "country_code": "AU",
  "region": "New South Wales",
  "city": "Sydney",
  "latitude": -33.8688,
  "longitude": 151.2093,
  "timezone": "Australia/Sydney",
  "isp": "Cloudflare, Inc",
  "asn": "AS13335",
  "org": "Cloudflare, Inc"
}

返回字段说明：

字段	类型	说明
ip	string	查询的 IP 地址
country	string	国家名称（英文）
country_code	string	两位国家代码（如 AU、US、CN）
region	string	州/省级行政区
city	string	城市名称
latitude	number	纬度
longitude	number	经度
timezone	string	时区标识（IANA 格式）
isp	string	互联网服务提供商
asn	string	自治系统编号
org	string	所属组织

在 IPIPAI 中的集成方式

IPIPAI 服务端在处理 analyze 请求时，会并行调用多个数据源（包括 OpenIPAPI）来构建 IP 的身份信息。OpenIPAPI 主要负责提供精确的地理位置字段（国家、城市、经纬度、时区），而 IPIPAI 自有引擎负责风险评估、AI 服务检测和网络质量测量。这种多数据源融合策略确保了地理位置信息的准确性和全面性。

如果你只需要 IP 的地理位置信息而不需要完整的 IP 画像，也可以直接调用 OpenIPAPI 的公开接口。两者是互补关系：OpenIPAPI 提供基础位置数据，IPIPAI 在此之上叠加了 AI 情报层。

AI Agent 发现机制

IPIPAI 为 AI Agent 设计了完整的自动发现机制，让大模型能够自主发现并理解可用的工具，无需开发者手动配置。这套机制由四个入口组成，分别面向不同的发现场景。

robots.txt — AI 爬虫友好策略

IPIPAI 在 robots.txt 中声明了 AI 爬虫友好策略，明确告知搜索引擎和 AI Agent 哪些路径可以爬取、哪些路径包含机器可读的工具定义。这确保了 IPIPAI 的 API 能力可以被主流 AI 搜索引擎（如 Perplexity、ChatGPT Search）索引和引用。

# robots.txt 节选
User-agent: *
Allow: /
Allow: /agents.md
Allow: /llms.txt
Allow: /api/v2/discovery

/agents.md — Agent 权威指南

/agents.md 是面向 AI Agent 的权威集成指南，以 Markdown 格式编写。它详细描述了每个 API 工具的用途、参数定义、返回格式和调用示例。Agent 读取这个文件后，就能完整理解 IPIPAI 提供的能力，并自主决定如何调用。

与传统的 API 文档不同，agents.md 是专门为 LLM 的上下文窗口优化的——它使用简洁的结构化 Markdown，避免冗长的视觉装饰，确保在有限的 token 预算内传递最大的信息密度。

/llms.txt — LLM 友好概览

/llms.txt 遵循 llms.txt 社区规范，提供一个更精简的 LLM 友好概览。它以纯文本格式列出 IPIPAI 的核心能力、关键端点和快速开始指南，适合作为 LLM 的系统提示或上下文注入。

这两个文件分工明确：llms.txt 提供鸟瞰式概览，agents.md 提供详细的操作手册。Agent 可以根据需要选择读取哪一个。

/api/v2/discovery — 机器可读工具清单

这是最重要的发现入口。/api/v2/discovery 端点返回一个机器可读的 JSON 工具清单，包含每个工具的名称、描述、参数 schema 和返回类型定义。Agent 无需预配置即可读取这个清单，然后自主编排调用链。

// 获取工具清单
const tools = await client.discovery();

// tools 示例结构
// [
//   {
//     "name": "analyze",
//     "description": "统一网络情报分析",
//     "parameters": { "ip": "string", "checkServices": "boolean" },
//     "endpoint": "/api/v2/analyze",
//     "method": "POST"
//   },
//   ...
// ]

这种基于运行时发现的设计意味着：当 IPIPAI 服务端新增工具或更新参数时，Agent 能在下次调用 discovery() 时自动感知，无需更新 SDK 或重新部署。

浏览器端使用

SDK 的 UMD 构建版本通过 CDN 引入后，可以在浏览器中直接使用，无需构建工具或打包器。这对前端开发者集成 IP 检测功能到网页中极为方便——比如在用户访问时自动检测其 IP 质量，或在管理后台展示 IP 评分。

CDN 引入方式

<script src="https://unpkg.com/@ipipai/sdk@latest/dist/index.min.js"></script>
<script>
  const client = new IPIPAIClient({ apiKey: 'your-api-key' });
  client.analyze('8.8.8.8').then(r => console.log(r.ipai_score));
</script>

UMD 版本会将 IPIPAIClient 挂载到全局 window 对象上，引入后即可直接使用。建议在生产环境中锁定具体版本号（如 @ipipai/[email protected]）而非使用 @latest，以避免版本漂移导致的意外行为。

安全性注意事项

在浏览器端使用时需要注意：API Key 会暴露在前端代码中。对于公开的 IP 查询场景，建议使用专为前端设计的受限 Key（限制来源域名、限制调用频率、限制可访问的端点）。对于敏感场景，应通过自己的后端代理转发请求，不在前端直接暴露 API Key。

TypeScript 完整类型支持

在 TypeScript 项目中，SDK 提供完整的类型定义，从初始化到响应解析全程有类型提示：

import { IPIPAIClient } from '@ipipai/sdk';
import type { AnalyzeResponse, ReputationResponse } from '@ipipai/sdk';

const client = new IPIPAIClient({ apiKey: '...' });
const result: AnalyzeResponse = await client.analyze('8.8.8.8');
// result.ipai_score, result.grade, result.ai.chatgpt.accessible 全部有类型提示

类型定义覆盖了所有七个方法的请求参数和响应结构，包括嵌套对象（如 result.ai.chatgpt.accessible）和可选字段。IDE 会在你输入 result. 时自动弹出所有可用字段，并在类型不匹配时报错。

应用场景

IPIPAI SDK 适用于任何需要 IP 情报的场景。以下是四个最典型的应用方向：

AI Agent 集成

为 LLM 工具调用提供 IP 情报能力，Agent 可在对话中实时查询 IP 评分和 AI 服务可用性。这是 SDK 设计的核心场景。例如，当用户问"我用的代理能上 ChatGPT 吗"，Agent 调用 analyze 方法获取当前 IP 的完整画像，然后用自然语言回答用户。

在 LangChain 中，可以将 analyze 封装为一个 Tool：

from langchain.tools import Tool

def ip_analyze(ip: str) -> dict:
    import requests
    resp = requests.post(
        "https://ipipai.com/api/v2/analyze",
        json={"ip": ip, "check_services": True, "lang": "zh"},
        headers={"X-API-Key": "your-api-key"}
    )
    return resp.json()

ip_tool = Tool(
    name="ip_analyze",
    description="查询 IP 的评分、AI 服务可用性和风险等级",
    func=ip_analyze
)

跨境电商

批量检测 VPS 和代理 IP 质量，评估多店铺运营的 IP 纯净度和封号风险。跨境电商运营者经常需要为不同店铺分配不同的 IP，如果 IP 质量差（评分低、被标记为代理），可能导致店铺被平台风控甚至封号。

通过 rateNode 方法可以批量评测 IP 池中每个 IP 的五维星级，筛选出最适合运营的高质量 IP。结合 reputation 方法还可以定期复查 IP 信誉，及时发现被加入黑名单的 IP。

代理节点筛选

结合 rateNode 方法对代理节点进行五维星级评定，筛选最优节点。代理服务提供商可以用 SDK 自动化测试所有节点的质量，按评分排序展示给用户。用户也可以用 SDK 自己测试购买的代理套餐实际质量。

五维评分让筛选维度更精细——不只是"能用/不能用"的二分判断，而是能看到每个维度的具体表现。例如一个代理可能 AI 可用性满分但网络质量一般，用户可以根据自己的需求（是要上 ChatGPT 还是要看 Netflix）选择最合适的节点。

安全审计

通过 reputation 接口快速评估 IP 信誉，检测代理、Tor、黑名单状态。安全团队可以用 SDK 批量审计访问日志中的 IP，自动标记高风险来源。对于自建服务的运营者，可以在注册、登录等关键环节实时检测用户 IP 的风险等级，对高风险 IP 触发额外验证。

// 安全审计示例：批量检测访问日志中的 IP
const suspiciousIPs = ['1.2.3.4', '5.6.7.8', '9.10.11.12'];

for (const ip of suspiciousIPs) {
  const rep = await client.reputation(ip);
  if (rep.score > 60 || rep.proxy || rep.tor) {
    console.log(`[告警] ${ip} 风险等级: ${rep.level} (分数: ${rep.score})`);
    console.log(`  代理: ${rep.proxy}, Tor: ${rep.tor}, 托管: ${rep.hosting}`);
  }
}

开源与专有的边界

IPIPAI 在开源和专有之间划定了清晰的边界，既保证了核心算法的持续投入，又让社区能自由使用客户端工具。理解这条边界有助于你评估 SDK 的适用性和长期可维护性。

开源部分（MIT 许可证）

@ipipai/sdk（SDK 客户端）以 MIT 许可证开源，你可以自由使用、修改、分发、商用。具体包括：

• SDK 的全部源代码（TypeScript 源文件、构建配置、类型定义）
• 所有 API 调用的封装逻辑（请求构造、响应解析、错误处理）
• 类型定义文件（.d.ts）
• 示例代码和文档

MIT 许可证是最宽松的开源许可证之一，不要求开源你的衍生作品，也不限制商业使用。你可以在闭源商业产品中自由使用 SDK。

专有部分（闭源）

以下组件为 IPIPAI 专有闭源代码，不包含在 SDK 中：

• IPIPAI MCP 服务端 — 处理 API 请求的后端服务
• IPIPAI Score 评分算法 — 五维评分的计算逻辑和权重模型
• MMDB 数据库 — IP 地理位置和 ASN 数据
• 风险检测引擎 — 代理/Tor/黑名单检测逻辑
• 后端基础设施 — 多节点探测网络和数据管道

这种架构的优势

SDK 通过 HTTP 调用服务端 API，算法在服务端运行——这意味着你获得的是一个永远最新的评分引擎，无需关心数据更新和算法维护。具体优势包括：

• 算法持续优化 — 评分模型会根据新的威胁情报和使用反馈持续调优，所有用户立即受益。
• 数据实时更新 — IP 黑名单、ASN 数据、地理位置库由服务端定期更新，客户端无需同步。
• 客户端极简 — 4KB 的体积不会拖累你的项目，零依赖不会引入安全风险。
• 服务端可控 — 可以统一控制调用频率、防止滥用、保障服务质量。

资源链接

以下资源帮助你快速接入 IPIPAI MCP 层。建议从 GitHub 仓库开始了解 SDK 全貌，然后参考 MCP 文档进行集成，最后通过 Discovery 端点探索完整的工具能力。

快速接入清单

如果你想在最短时间内跑通第一个 IP 查询，按以下步骤操作：

1. 访问 GitHub 仓库 了解 SDK 设计理念。
2. 运行 npm install @ipipai/sdk 安装 SDK。
3. 在 IPIPAI 官网 获取你的 API Key。
4. 复制本文"三行代码开始"部分的示例，替换 API Key 即可运行。
5. 如需让 AI Agent 自动发现工具，调用 discovery() 获取工具清单。
6. 如需深入了解每个方法的参数和返回结构，参考 MCP 完整文档。

社区与反馈

SDK 是开源项目，欢迎在 GitHub 上提交 Issue 报告问题、提出功能建议或贡献代码。如果你在使用过程中遇到任何问题，或者有新的应用场景想讨论，都可以通过 GitHub Issues 与团队交流。社区贡献会经过代码审查后合并到主分支，并在下一个版本发布到 npm。