PART 4｜安装使用：十分钟跑起来
环境要求
Python 3.12 或 3.13 + uv（torch 尚无 3.14 wheel）。GPU 可选：CUDA / ROCm / Apple Silicon（MLX 自动启用）。
第一步：浏览器先试（可选）
官方 HuggingFace Space 跑着 Kev-4B 和 Kev-0.8B，零安装：huggingface.co/spaces/jaredpalmer/kev。
第二步：本地起服务
git clone https://github.com/jaredpalmer/kev.git && cd kev
uv sync --extra serve
uv run --extra serve python -m kev.serve --run jaredpalmer/kev-4b --port 8009
首次运行自动下载适配器与底座模型。--run 也接受本地 checkpoint 目录或 Hub revision。
第三步：发一个请求
curl -s localhost:8009/v1/systemone -H 'content-type: application/json' -d '{
"state": "Shoes arrived two weeks late and in the wrong size. Also I see two charges on my card.",
"model": "kev-latest",
"questions": {
"department": {"type": "choice", "instructions": "Which team should handle this?",
"criteria": {"returns": "Exchanges, refunds, wrong or damaged items",
"shipping": "Delivery status, delays, lost packages",
"billing": "Charges, invoices, payment problems"}},
"escalate": {"type": "noul", "instructions": "Does this need urgent human attention?"},
"frustration": {"type": "score", "instructions": "How frustrated is the customer?",
"criteria": ["Calm", "Frustrated", "Very angry"]}
}}'
响应（Kev-4B，Apple M5 bf16）：
{
"answers": {
"department": {
"type": "choice", "choice": "returns", "confidence": 0.21,
"probabilities": {
"returns": 0.47, "shipping": 0.28, "billing": 0.25 } },
"escalate": {
"type": "noul", "noul": 0.93 },
"frustration": {
"type": "score", "score": 1.44, "confidence": 0.34,
"probabilities": {
"0": 0.00, "1": 0.56, "2": 0.44 } }
},
"usage": {
"input_tokens": 101, "output_tokens": 161 },
"latency_ms": 495
}
注意 department 的概率分布如实反映了工单里的三个诉求——返回概率而不是单一标签，就是为了让你的代码按置信度路由。
第四步：Python 接入（已在用 Jev 的零改造）
from typesafe_sdk import Choice, Noul, Score, TypeSafeClient
client = TypeSafeClient(
api_key="local",
base_url="http://127.0.0.1:8009",
model="kev-latest",
)
response = client.system_one(
state="I was charged twice. Please fix this ASAP.",
questions={
"billing": Noul(instructions="Is this ticket about billing?"),
"tone": Choice(instructions="What is the customer's tone?",
criteria={
"calm": None, "frustrated": None, "angry": None}),
"urgency": Score(instructions="How urgent is this ticket?",
criteria=["can wait", "this week", "today"]),
},
)
云端部署（Modal，一条命令）
pip install modal && modal setup
curl -LO https://raw.githubusercontent.com/jaredpalmer/kev/main/skills/kev-deploy/scripts/kev_serve.py
KEV_API_KEY=$(openssl rand -hex 24) modal deploy kev_serve.py
得到 https://<workspace>--kev-api.modal.run，Bearer 鉴权，空闲缩容到零不计费（冷启动约 35 秒）。
常用环境变量
| 变量 | 作用 |
|---|---|
KEV_TEMPERATURE=1.0 |
关闭校准，返回原始概率 |
KEV_DTYPE=fp32 |
用与官方评测完全一致的 fp32 路径 |
KEV_API_KEY |
要求 Bearer 鉴权 |
KEV_DATE_FACTS=1 |
给 state 里的日期对自动附加天数差（补日期减法短板） |
我实测的环境坑（Windows 用户必读）
- 代理环境半开挂死：本机开了 HTTP 代理时，训练/服务子进程会对 HuggingFace 做 HEAD 请求然后无限挂起（CPU/GPU 全 0 空转）。解法：模型权重预先本地化，训练与服务一律
HF_HUB_OFFLINE=1并清空代理变量。 - POSIX-only 导入：
train.py/serve.py顶层import resource，测试引fcntl。Windows 下用 runpy 预注入 no-op stub（这两个模块在上游只用于峰值内存统计和文件锁，stub 不影响训练数值），不要改上游仓库。 - HuggingFace 直连不通：国内环境设
HF_ENDPOINT=https://hf-mirror.com。 --max_steps 0的语义是「无上限」而不是「不训练」。
其他入口
- Playground（
cd playground && npm install && npm run dev）：网页里改 state 和问题、对比「打包问 vs 分开问」、做选项顺序扰动，还有个拿棋盘当输入的国际象棋 demo。 - Coding Agent 一键微调：
npx skills add jaredpalmer/kev@kev-finetune，agent 会面谈、找问题、造数据、在 Modal 上训完并部署端点，H100 一次约 1 美元。
