Metadata-Version: 2.4
Name: uip-sdk
Version: 0.3.0
Summary: UIP — Universal Inference Platform Python SDK (federation + credits + multi-tenant)
Author-email: Zhu Wenbo <zwb.2002@tsinghua.org.cn>
License-Expression: Apache-2.0
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: httpx>=0.27

# UIP Python SDK

Universal Inference Platform 的 Python 客户端库。

## 安装

```bash
pip install uip-sdk
```

## 快速开始

```python
from uip_sdk import UIPClient

# 方式 1: API Key
client = UIPClient(api_key="ggw-xxx...")

# 方式 2: JWT Token
client = UIPClient(token="eyJhbGciOiJIUzI1NiIs...")

# 方式 3: 环境变量 (UIP_API_KEY)
client = UIPClient()
```

## 推理

### 对话 (Chat Completions)

```python
resp = client.chat(
    messages=[{"role": "user", "content": "你好"}],
    model="qwen2.5:7b",
)
print(resp.text)
```

### 流式生成

```python
for chunk in client.generate("写一首关于春天的诗", stream=True):
    print(chunk.text, end="", flush=True)
```

### Rerank (文档重排序)

```python
results = client.rerank(
    query="CBA季后赛战术分析",
    documents=["CBA联赛采用胜率决定排名", "篮球三分线距离为6.75米", "广东队采用全场紧逼战术"],
    model="Qwen3-Reranker-0.6B",
    top_n=2,
)
for r in results.results:
    print(f"#{r.index}: {r.document[:30]}... score={r.relevance_score:.2f}")
```

### 批量推理

```python
batch = client.batch(prompts=["你好", "介绍你自己"], model="qwen2.5:7b")
for item in batch.results:
    print(f"[{item.index}] {item.response[:50]}")
```

### 嵌入向量

```python
resp = client.embed(input="需要向量化的文本", model="bge-m3:567m")
print(len(resp.embedding))  # 768
```

### UMR 通用推理（17 种模态）

```python
# SDXL 文生图
result = client.infer("sdxl:base", {"prompt": "a cat"})

# 目标检测
result = client.infer("yolov8:m", {"image": "photo.jpg"})

# ASR 语音识别
result = client.infer("whisper:large-v3", {"audio": "speech.wav"})

print(result.modal_type)
```

### 指定调度策略

```python
client.with_strategy("least_queue").generate("hi")
```

## 联邦推理

UIP→UIF→UIS→UIG 跨机构推理链路，需方通过 SDK 向供方发起推理请求。

```python
# 自动选择最优供方
result = client.federated_infer(
    model_id="qwen2.5:7b",
    payload={"prompt": "介绍中国体育教育发展"},
)
print(result.supplier_unit)    # 供方单位 ID
print(result.supplier_node)    # 供方 GPU 节点名
print(result.cost_rmb)         # 人民币费用
print(result.cost_credits)     # 积分费用

# 指定供方 + GPU 类型偏好 + 价格上限
result = client.federated_infer(
    model_id="qwen2.5:7b",
    payload={"prompt": "你好"},
    target_unit="tsinghua-sports",    # 指定供方单位
    prefer_gpu_type="rtx_5090",       # GPU 类型偏好
    max_price_credits=10.0,           # 积分价格上限
)
```

## 训练管理

```python
# 提交训练任务（含 gpu_type 和 unit_id 多租户隔离）
job = client.submit_job(
    model="qwen2.5:7b",
    name="fine-tune-v1",
    n_gpus=1,
    epochs=3,
    gpu_type="rtx_5090",       # GPU 类型追踪
    unit_id="tsinghua-sports",  # 多租户命名空间隔离
)
print(job["job_id"])

# 任务列表 / 详情 / 取消
jobs = client.list_jobs(status="running")
detail = client.get_job("job-xxx")
client.cancel_job("job-xxx")

# 训练日志（长轮询 / SSE 流式）
logs = client.get_job_logs("job-xxx", tail=50)
for line in client.stream_job_logs("job-xxx"):
    print(line, end="")

# 断点 / 数据集 / 指标
ckpts = client.list_checkpoints("job-xxx")
latest = client.get_latest_checkpoint("job-xxx")
datasets = client.list_datasets()
metrics = client.get_training_metrics("job-xxx")
```

## 计费与余额

```python
from uip_sdk import BalanceResponse

# 查询余额（双轨：人民币 + 积分）
bal: BalanceResponse = client.get_balance()
print(f"人民币: ¥{bal.balance_rmb:.2f}")
print(f"积分:   {bal.balance_credits:.0f} credits")
print(f"冻结:   ¥{bal.frozen_rmb:.2f} / {bal.frozen_credits:.0f} credits")

# 快速查询积分
credits = client.get_credits()

# 交易记录
txns = client.get_transactions(page=1, page_size=20, currency="credits")
for item in txns.items:
    print(f"{item.created_at} {item.tx_type}: {item.amount} {item.currency} — {item.description}")

# 管理员充值
resp = client.recharge(user_id=42, amount=100.0, currency="credits", description="赠送积分")
print(f"充值成功: tx_id={resp.tx_id}, balance_after={resp.balance_after}")
```

## License

Apache License 2.0. Copyright (c) 2026 Zhu Wenbo (zwb.2002@tsinghua.org.cn).
