logan-markewich/jeff
# jeff 学习卡
一、一句话定位
自托管 TypeSafe 分类推理服务，提供 choice（选选项）、score（定等级）、noul（判概率）三类 API，成本远低于官方但精度略逊。
二、核心技术/架构亮点
- 基于 GLiFormer 400M 参数模型，支持 CUDA / MPS / CPU 自动选择，也可用 ONNX 在 CPU 上降精度运行
- 动态批处理：通过 `JEFF_MAX_BATCH` / `JEFF_MAX_WAIT_MS` 控制吞吐与延迟的平衡
- 兼容官方 `typesafe-sdk`，只需修改 `TYPESAFE_BASE_URL` 即可切换后端
- 温度缩放校准概率（默认 3.2），提供置信度计算公式
- 支持隔离编码（noul 单独通过编码器），减少问题间干扰
三、适用场景与目标用户
- 希望降低 TypeSafe API 调用成本的团队或个人开发者
- 需要离线或内网部署结构化分类推理（如客服工单分级、情绪检测、紧急程度判断）
- 对快速原型验证、低成本实验有需求，且能容忍部分推理精度损失（详见 Benchmark）
四、可动手动作
1. 本地启动：`git clone` 后 `uv sync --extra dev`，下载模型 `hf download knowledgator/gliformer-large-v1`，设置 `JEFF_API_KEYS=devkey` 并 `uv run jeff`
2. 接入 SDK：用 `TypeSafeClient(api_key, base_url="http://localhost:8000")` 调用（README 中已提供完整示例）
3. curl 测试：直接 POST `/v1/systemone`，参数格式与官方一致
4. 部署到 Modal：按 README 步骤 `modal deploy`，可使用 L4 GPU 并获得约 50 req/s 吞吐
5. 借鉴思路：其动态批处理器、温度校准、模型取舍策略可复用于其他自托管推理服务
五、学习优先级
P0（本周动手）
理由：启动成本极低，十分钟内即可本地跑通完整分类流程，验证思路立竿见影；且与 TypeSafe 生态无缝衔接，能立即用于真实项目。
六、主题标签
类型化决策⌂