类Jev项目Kev从入门到实战(4)：安装使用：十分钟跑起来
# PART 4｜安装使用：十分钟跑起来 ## 环境要求 Python 3.12 或 3.13 + [uv](https://docs.astral.sh/uv/)（torch 尚无 3.14 wheel）。GPU 可选：CUDA / ROCm / Apple Silicon（MLX 自动启用）。 ## 第一步：浏览器先试（可选） 官方 HuggingFace Space 跑着 Kev-4B 和 Kev-0.8B，零安装：huggingface.co/spaces/jaredpalmer/kev。 ## 第二步：本地起服务 ```bash 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。 ## 第三步：发一个请求 ```bash 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）： ```json { "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 的零改造） ```python 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，一条命令） ```bash 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://--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 美元。
