配方 06 动手实践 11 分钟更新 2026年9月27日

本地部署检查清单

托管 Jev 仍走 TypeSafe API。本页先写本机调用该 API，再列独立的、提供 System One 形状 HTTP 的本地运行时。

TypeSafe 公开文档描述的是托管 Jev：Playground、POST https://api.typesafe.ai/v1/systemone 与客户端 SDK。文档没有发布 Jev 权重或本地 Jev 二进制。你在设备上跑的是另一个项目。

本站非官方，与 TypeSafe 及下列本地工具均无隶属关系。

1. 在本机调用托管 Jev

官方路径：

在 TypeSafe dashboard 创建 API 密钥。
把密钥放进进程环境变量 TYPESAFE_API_KEY — 不要进 git（快速开始、Python SDK）。
安装客户端：pip install typesafe-sdk 或 uv add typesafe-sdk（Python >= 3.10），或直接发 HTTP（快速开始）。
POST 到 https://api.typesafe.ai/v1/systemone，带 Authorization: Bearer $TYPESAFE_API_KEY，模型 jev-latest（快速开始）。

可选托管路径：Vercel AI Gateway 模型 typesafe-ai/jev（用 Gateway 凭证，不只是裸 TypeSafe 密钥）。见 Vercel AI Gateway · Jev。

可先在 Playground 感受接口。

2. `.env`（已 gitignore，仅占位）

本仓库已忽略 .env 与 .env.*（.env.example 除外）。复制 .env.example 并填占位符 — 不要写真实密钥：

# 托管 Jev — https://docs.typesafe.ai/introduction/quickstart
TYPESAFE_API_KEY=

# 可选：指向本地 TypeSafe 兼容服务（由 Ollaya 文档，不是 TypeSafe）
# TYPESAFE_BASE_URL=http://localhost:11435
# TYPESAFE_DEFAULT_MODEL=laya

不要把密钥贴进页面、聊天或已提交文件。

3. 可在本地运行的独立工具

这些不是托管 Jev。它们发布自己的权重或运行时，有的提供 TypeSafe 形状的 HTTP。

工具	官方文档写明可运行的内容	文档中的硬件 / 系统	官方安装
Laya（README）	包 `laya`；检查点 `laya`、`laya-multilingual`、`laya-typed-decisions`；可选 `laya-serve` 提供 `POST /v1/systemone`	Python 3.10+；macOS / Linux / Windows；可选 CUDA、MPS、Intel XPU	`python -m pip install laya`；服务额外依赖：`pip install "laya[serve]"` 后 `laya-serve`（绑定 `0.0.0.0:8000`）
Ollaya（常见问题）	FAQ 列出的开源族（含 `laya`、`decider`、`nli`、`gliclass`、`kev`、`decision`、`qwen3guard`、`von`、`winnow`、`jevk5`）	见第 4 节	桌面应用；`curl -fsSL https://ollaya.dev/install.sh \| sh`；`irm https://ollaya.dev/install.ps1 \| iex`；Docker `ghcr.io/ollaya-dev/ollaya`
Kev（README）	`kev.serve`，Hub 运行如 `jaredpalmer/kev-4b`	Python 3.12 或 3.13 + uv；CUDA / ROCm / MLX；各规格 GPU/内存见 README（从 Kev-4B 起步）	克隆仓库，`uv sync --extra serve`，`uv run --extra serve python -m kev.serve --run jaredpalmer/kev-4b --port 8009`
SemIf（原 OpenJev）（README）	在开源模型上的 Jev 风格接口	见 SemIf README	不是 TypeSafe 权重。见 OpenJev 与 Jev

Ollaya FAQ：Ollaya 与 Ollama 无隶属关系，也 与 TypeSafe 无隶属关系。默认监听 127.0.0.1:11435。文档写明状态与问题不离开本机；网络只用于拉取模型。

4. Ollaya 详解（官方文档）

本节只依据 Ollaya 自己的站点：ollaya.dev、Download、Quickstart、常见问题、CLI、API、TypeSafe compatibility，以及 ollaya-dev/ollaya。

与 Ollama 无隶属关系，与 TypeSafe 无隶属关系。 FAQ 写明借用 Ollama 的使用体验（单一二进制、pull / run / serve、Modelfile、本地 REST），用在决策模型上。兼容范围写明覆盖 API，不是 TypeSafe 的模型或 Jev 权重。

能否在本地运行

能。Quickstart：“Ollaya runs open decision models on your own machine.” 服务默认监听 127.0.0.1:11435，模型在本机运行。FAQ：状态与问题从不记录；网络只用于拉取模型。端口 11435 紧挨 Ollama 默认 11434，可并存。

Ollaya 是单一二进制（CLI、服务、运行器）。ollaya run 在需要时启动服务，首次使用会拉取并加载模型。原生 API 为 /api/*；TypeSafe 形状 API 为 /v1/*。

要求（Download + FAQ）

平台	这些页面写明的内容
Linux	x86-64 或 ARM64，glibc 2.38 或更新（Ubuntu 24.04、Debian 13、Fedora 39、RHEL 10 或更新）。一定可以 CPU。NVIDIA GPU 可选：驱动 R580 或更新（CUDA 13），限 x86-64。安装器不装驱动。
macOS	Apple silicon（arm64），macOS 14 或更新。Download：CPU。FAQ：`laya` 与 `nli:modernbert-large` 可通过 MLX 跑在 Apple GPU；其余在 CPU。`winnow` 等 GGUF 族走 llama.cpp，可能用 Apple silicon GPU（Metal）；FAQ 写明对齐检查在 CUDA 与 x86-64 CPU 上做过，Metal 尚未做。
Windows	Windows 10 或 11，64 位 x86。桌面应用：CPU。命令行：CPU，若有 NVIDIA GPU（驱动 R580+，CUDA 13）则使用。也可在 WSL 2 用 Linux 安装器；回环服务可让 Windows 程序访问 `localhost:11435`。
Docker	`ghcr.io/ollaya-dev/ollaya` 支持 linux/amd64 与 linux/arm64（CPU）。NVIDIA 用 `:cuda`（linux/amd64）。需要 NVIDIA Container Toolkit 与支持 CUDA 13 的宿主机驱动（R580 或更新）。FAQ：较旧的 Linux 发行版也可用 Docker。
GPU	不需要。 FAQ：在 x86-64 Linux 与 Windows 上，命令行在检测到 NVIDIA GPU 时使用它。桌面应用在 CPU 上跑模型。安装脚本仅在发现 GPU 时下载 CUDA 库（Download 写约 1 GB）。

tarball：GitHub Releases 与 sha256sum.txt（Download）。

安装（官方命令）

Linux 与 macOS：

curl -fsSL https://ollaya.dev/install.sh | sh

Windows（PowerShell；按用户安装，不需要管理员权限）：

irm https://ollaya.dev/install.ps1 | iex

或桌面应用（同一套本地 API；若要用 ollaya 命令，再装命令行）。Download 写明 Windows 应用尚未代码签名；若 SmartScreen 拦截，文档写 More info → Run anyway。

Docker（CPU）：

docker run -d --name ollaya -p 11435:11435 -v ollaya:/home/ollaya/.ollaya ghcr.io/ollaya-dev/ollaya

Docker（NVIDIA）：

docker run -d --name ollaya --gpus=all -p 11435:11435 -v ollaya:/home/ollaya/.ollaya ghcr.io/ollaya-dev/ollaya:cuda

然后 docker exec -it ollaya ollaya run laya。模型保存在 ollaya volume。

在 Linux 上，若有 systemd 且脚本有 root，会把 ollaya 服务装到 127.0.0.1:11435。第一个模型：ollaya run laya（Quickstart）。文档写明 laya 是路由器：英文 → laya:en，其他语言 → laya:multilingual；拉取 laya 会拉取两者。

配置（CLI / API 环境变量）

见 CLI 与 API 页。systemd 单元用 sudo systemctl edit ollaya 加 Environment=。

变量	默认	这些页面写明的作用
`OLLAYA_HOST`	`127.0.0.1:11435`	绑定地址与 CLI 目标。回环绑定也会听 `[::1]`。
`OLLAYA_MODELS`	`~/.ollaya/models`	模型存储
`OLLAYA_KEEP_ALIVE`	`5m`	最后一次请求后再保持加载多久
`OLLAYA_MAX_LOADED_MODELS`	`3`	同时保持加载的模型数
`OLLAYA_MAX_QUEUE`	`512`	进行中的决策超过此数则 `503 QUEUE_FULL`
`OLLAYA_LOAD_TIMEOUT`	`5m`	加载超时则 `500 MODEL_LOAD_FAILED`
`OLLAYA_DEVICE`	`auto`	`auto`（安装器加入 CUDA 库则用 NVIDIA GPU，否则 CPU）、`cpu` 或 `cuda`
`OLLAYA_API_KEY`	未设置	要求 `Authorization: Bearer`；CLI 也会发送同一值
`OLLAYA_ORIGINS`	未设置	额外允许的浏览器 Origin，逗号分隔
`OLLAYA_REGISTRY`	`ollaya.dev`	模型名中的默认 registry 主机

不要把真实密钥写入 git。若设置 OLLAYA_API_KEY，只放在进程环境或已 gitignore 的文件里。

Ollaya 文档中的坑

默认模型不对。 TypeSafe SDK 0.7.1 若不设 TYPESAFE_DEFAULT_MODEL 或不传入 model，仍会发送 jev-latest。Ollaya 返回 MODEL_NOT_FOUND（兼容页示例为 jev-latest:latest）。见 TypeSafe compatibility。
macOS 系统 HTTP 代理。 TypeSafe SDK（经 httpx）可能把 localhost 也走代理。在 TYPESAFE_BASE_URL 旁设置 NO_PROXY=localhost,127.0.0.1，否则状态会离开本机，服务未启动时还可能表现为 502 status code (no body)。见 TypeSafe compatibility。
绑定超出回环。 OLLAYA_HOST=0.0.0.0 会让能访问该端口的人执行决策以及拉取、删除、创建模型。若这样做，应设置 OLLAYA_API_KEY。监听非回环且未设密钥时，服务会打警告。服务本身不终止 TLS。见 API · Security。
HTTP 不会隐式拉取。 应用需调用 /api/pull；ollaya run 会先拉取。见 API。
Windows SmartScreen。 桌面安装包未签名。见 Download。
Linux glibc。 需要 2.38 或更新；更旧发行版用 Docker。见常见问题与 Download。
停止服务。 不带模型的 ollaya stop 只停你启动的服务，不停 Linux systemd 服务；后者用 sudo systemctl stop ollaya。见 CLI。
CUDA 上的 fp16。 CUDA GPU 默认 fp16 图，在接近平局时可能与 fp32 不同。要与参考对齐可钉 -fp32 标签。见常见问题。
/v1/* 上状态过长。 状态装不进开源模型上下文时，/v1/* 返回 422 STATE_TRUNCATED，而不是用截断前缀作答。见 TypeSafe compatibility。

5. 把 TypeSafe SDK 指到本地服务

仅在该项目文档写明时这样做。

Ollaya（SDK 0.7.1；TypeSafe compatibility）：

export TYPESAFE_BASE_URL=http://localhost:11435
export TYPESAFE_API_KEY=local
export TYPESAFE_DEFAULT_MODEL=laya
export NO_PROXY=localhost,127.0.0.1

Kev（构造参数，占位密钥；Kev README）：

from typesafe_sdk import TypeSafeClient
client = TypeSafeClient(api_key="local", base_url="http://127.0.0.1:8009", model="kev-latest")

Laya serve： Laya README 写明已有 Jev 客户端只需改 baseUrl。若设置 LAYA_API_KEY，请求需带 Authorization: Bearer。

6. 常见坑（每条都链到官方出处）

托管 Jev 返回 401。 缺少或无效的 TYPESAFE_API_KEY、错误头或错误主机。见 API 返回 401 与快速开始。
SDK 仍向 Ollaya 发送 jev-latest。 设置 TYPESAFE_DEFAULT_MODEL 或传入 model。Ollaya 将此记为 MODEL_NOT_FOUND。见 TypeSafe compatibility。
macOS 代理 + Ollaya。 设置 NO_PROXY=localhost,127.0.0.1。见 TypeSafe compatibility。
Ollaya 绑到非回环。 若 OLLAYA_HOST 不是回环，应设置 OLLAYA_API_KEY。见 API · Security。
置信度阈值不能照搬。 Laya 文档写明 confidence 公式不同，从 Jev 搬来的阈值不可沿用。见 Laya README。
Python / 虚拟环境不对。 Laya：安装与脚本不在同一解释器时会出现 ModuleNotFoundError: No module named 'laya'（README）。Kev：仅 3.12/3.13；torch 无 3.14 wheel（README）。
首次下载。 Laya 与 Kev 需要一次性访问 Hugging Face（或 Hub）（Laya、Kev）。Ollaya 从作者仓库拉取并校验 sha256（常见问题）。
Windows + NVIDIA。 Windows 命令行在检测到 NVIDIA GPU 时使用它；桌面应用仍走 CPU。WSL 2 + Linux 安装器也有文档。见常见问题与 Download。
SemIf 分数 ≠ 托管 Jev。 SemIf 复现的是接口模式，不是 TypeSafe 权重。见 SemIf README 与 OpenJev 与 Jev。
密钥进库。 TypeSafe 文档要求把 TYPESAFE_API_KEY 放在进程环境（Python SDK）。密钥只放在已 gitignore 的 .env 或环境变量里 — 不要进 git。

来源

快速开始
TypeSafe Python SDK
System One
Vercel AI Gateway · Jev
NandhaKishorM/laya
Ollaya · Download · 常见问题 · Quickstart · CLI · API · TypeSafe compatibility
ollaya-dev/ollaya
jaredpalmer/kev
SemIf

下一步：第一次 System One 调用（LearnJev）上一步：候选字段 + 代码校验