infra-data-client — InfraX data-service 官方 Python SDK

InfraX data-service（统一市场数据微服务，/bars / /factors/* / /snapshots / /ticker / /symbols/* / /stats / /health）的官方 Python 客户端。B 端（AItrader 侧）用这一个类替换各自重复实现的 data_client.py / factor_client.py，收敛鉴权、TLS、限流、时间换算口径。

• 版本：0.4.0（SemVer；契约变更走 minor，bug 修复走 patch，AItrader 侧升级 SDK 即可，无需改业务代码）
• 依赖：requests>=2.25（Python ≥ 3.9）

安装

# 本地构建安装
cd projects/data/sdk/python
pip install .

# 或直接 git 引用（发布到私有源后改用 pip install infra-data-client）
pip install "git+https://<你的仓库>/infraX-1.git#subdirectory=projects/data/sdk/python"

# 开发模式（改代码即生效）
pip install -e .

快速开始

from infra_data_client import InfraDataClient

client = InfraDataClient(
    base_url="https://infrax.0xainet.top/api/data",  # 生产统一域名；本机直连 http://127.0.0.1:9112
    api_key="infrax-bridge-...",         # X-Service-Key 自动携带（DS-12）
    verify=True,                         # 生产域名证书有效（Cloudflare Origin CA），无需关闭校验
)

# K 线（start/end 秒或毫秒均可，自动归一化）
bars = client.get_bars("BTC/USDT", timeframe="1h", limit=10)

# 最新因子（含 DS-13 ML 因子）
factors = client.get_current_factors("BTC,ETH")

# 实时报价
ticker = client.get_ticker("BTC/USDT", market_type="swap")

# 符号解析 / 搜索
resolved = client.resolve_symbol("BTC")
hits = client.search_symbols("btc", market="crypto", limit=10)

# 语义图谱（GF-3 / REQ-G1 / REQ-G2 / REQ-G2.1 / REQ-G2.5，0.4.0）
graph = client.get_graph_factors(["BTC", "ETH"])      # 图谱因子
entities = client.get_graph_entities("BTC")            # 力导向图（一跳子图）
edges = client.get_graph_edges(["BTC", "ETH"])         # 相关性图边
history = client.get_graph_history(["BTC", "ETH"], days=7)  # gf_* 日频历史
rag = client.rag_retrieve("比特币 ETF 资金流向", top_k=3)   # 只读 RAG 检索

API 一览

核心能力

• 鉴权内置：api_key 自动写入 X-Service-Key 请求头（DS-12 契约），调用方零配置。
• TLS 可配置：verify=False 应对生产证书不可信现状（同时抑制 InsecureRequestWarning）。
• 429 限流重试：命中 429 自动重试，优先 Retry-After 头，无则指数退避 backoff * 2^attempt；max_retries=0 关闭重试。
• fail-silent（默认开）：网络错误 / 非 2xx（401/404/500…）返回 None，业务不中断；fail_silent=False 时抛 InfraDataError(status, message) 便于排查。
• 时间单位归一化：start/end 传秒或毫秒均可（≥10^12 视为毫秒），SDK 统一换算后上送。
• 类型注解：全部方法与返回类型标注，IDE 与静态检查友好；Client 支持上下文管理器（自动关闭连接池）。

图谱端点调用规则（0.4.0）

语义图谱类端点（/factors/graph*、/rag/retrieve）统一收敛到 data-service 单入口单 key：B 端仅需一个 dx_* key，SDK 自动写入 X-Service-Key；data-service 内部持 ragservicer/ml-service 服务 key 透传，调用方零额外鉴权。

GET /factors/graph（图谱因子，GF-3）

• 参数：symbols 逗号分隔（"BTC,ETH" 或 ["BTC","ETH"]）。顺序无关——服务端按 symbol 集合键控缓存，BTC,ETH ≡ ETH,BTC（重复请求直接命中缓存）。
• 缓存行为（2026-08-24 P0+P1 优化后）：
  • data-service 多槽缓存：TTL 3600s、上限 32 组（最旧淘汰）；并发同集合请求单飞（只构建一次，防缓存击穿）
  • ragservicer 侧因子进程缓存 1h，服务启动时预热常用 10 币种（BTC,ETH,SOL,BNB,XRP,DOGE,ADA,AVAX,LINK,DOT）→ 重启后首请求即热
  • 冷缓存（新 symbol 组合）时延：单符号上游超时 5s，并行 fan-out 8 路 → 12 符号约 2s、10 符号预热后约 0.2s；缓存命中 <10ms
• 部分降级：某 symbol 上游失败时返回成功子集（不整体失败）；全部失败 → factors 空 + meta.warning
• 状态机：meta.status = "ready"（可消费）| "building"（未就绪，退避重试，建议 1s/2s/4s）；meta.warning 说明降级原因
• 建议：常规轮询场景（如每 15min）无需关注缓存；仅处理 building 状态做退避重试即可

GET /factors/graph/edges（相关性图边，REQ-G1）

• symbols 空 = 全图（默认）；limit 1~1000
• 构建中语义：meta.status="building" 时透传 meta.job_id（ml-service 后台构建，短 TTL 30s）→ 客户端按 job_id 轮询重试（间隔 ≥30s 避免空转），转 "ready" 后消费
• 图快照与 /factors/current 的 gf_community/gf_pagerank 同口径（同一图快照）

GET /factors/graph/entities（力导向图，REQ-G2.1）

• symbol 空 = top-N 全图（按 PageRank）；非空 = 该实体一跳子图
• namespace 枚举：market（金融主空间，默认）/ onchain / default；limit 1~500
• 数据源：ragservicer 共享金融知识图谱（default 租户）；building 时同上退避重试

GET /factors/graph/history（gf_* 日频历史，REQ-G2.5）

• symbols 空 = 全部；days 1~365（默认 90）；历史自 2026-08-18 起累积，不足时 series 为空（fail-silent）
• 回测 asof 语义（按自然日归一化，无未来函数）

POST /rag/retrieve（只读 RAG 检索，REQ-G2）

• 请求体：{"query": "必填", "namespaces": ["market","onchain"] | 省略=全部, "top_k": 10}
• namespace 枚举同上；返回各 namespace 的 context 片段，供 B 端自带 LLM 做知识增强
• fail-silent：无结果 → results 空 + meta.warning

通用规则

• 所有图谱端点 fail-silent 默认开（网络/非 2xx 返回 None）；排查用 fail_silent=False 捕获 InfraDataError(status, message)
• 429 自动重试（Retry-After 优先，指数退避兜底，max_retries 可调）——B 端高频轮询时建议保留
• 客户端侧无需自行串行/聚合多 symbol：服务端已并行 fan-out + 部分降级，一次调用拿全量子集

示例

• examples/quickstart.py — 全端点走查
• examples/ml_predictions_integration.py — ML 预测集成：快照优先 + ml-service 直连 data=null 兜底（含 /ml/cache/stats 就绪判断）

cd projects/data/sdk/python
python examples/quickstart.py --base-url http://127.0.0.1:9112 --api-key <KEY>
python examples/ml_predictions_integration.py --symbol BTC/USDT --model bolt \
    --data-url https://infrax.0xainet.top/api/data --data-key <KEY> --ml-url https://infrax.0xainet.top

发布（SemVer）

cd projects/data/sdk/python
pip install build
python -m build        # 产出 dist/infra_data_client-0.4.0-*.whl / .tar.gz
# 上传到私有 pip 源，或直接分发 wheel

契约变更规范：新增端点/参数 → minor；修复行为 → patch；破坏性变更 → major。