4.1 HTTP 服务与 Jev 协议兼容

4.1 HTTP 服务与 Jev 协议兼容

本节摘要：laya-serve 是官方自带的 FastAPI 服务（官方口径），装上 serve 扩展、一条命令启动，就得到一个走 POST /v1/systemone 的决策端点——与 Jev 同线协议，官方客户端改 baseUrl 即可直连（官方口径）。本节走完这条链路：启动与健康检查、一次完整的 curl 请求与返回解读、Python 客户端直连示例；然后讲 laya 侧的协议差异——同一端点背后是三个检查点加 Router，请求可以指定检查点或交给自动路由，返回带 checkpoint 字段，这是 Jev 单模型形态没有的行为。协议的字段级全景不在此展开，在《Kev 实战：训练并运行你自己的决策模型》第 01 章《协议与兼容》，本节只讲部署者需要知道的差异面。命令与字段为写法示意。

学习目标

• 启动 laya-serve、跑健康检查、发一次 /v1/systemone 请求并解读返回。
• 把 Jev 官方客户端的 baseUrl 指向 laya-serve 完成直连。
• 说出同线协议对架构的实际意义：混部、灰度与降级路径。
• 描述 laya 侧的多检查点路由行为如何体现在 HTTP 请求与返回里。

一、laya-serve 是什么

laya-serve 是随 laya 包提供的一个自包含 FastAPI 应用（官方口径）：装上可选扩展、敲一条命令，就把第 3 章那套 predict 能力暴露成了 HTTP 服务。它解决的问题是「调用方不在你的运行时里」——Go 服务、Node 网关、别队的脚本，只要能发 HTTP 就能调 laya。

# bash —— 安装与启动（写法示意，命令与端口参数以官方仓库 README 为准）
python -m pip install "laya[serve]"
laya-serve --host 0.0.0.0 --port 8000
# 首次启动会触发检查点下载（同第 3.1 节），等待就绪日志再压流量
​

启动后第一件事不是发请求，是健康检查：

# bash —— 健康检查（路径写法示意，以实际服务的路由表为准）
curl -s http://127.0.0.1:8000/health
# 预期：返回存活状态（具体字段以实测为准）
​

把健康检查当成部署的契约：后续容器健康探测（4.2 节）、负载均衡摘流、发布前冒烟，全都建立在它上面。

二、POST /v1/systemone：一次完整调用

# bash —— 一次决策请求（写法示意，字段以官方文档为准）
curl -s -X POST http://127.0.0.1:8000/v1/systemone \
  -H "Content-Type: application/json" \
  -d '{
    "state": "工单：订单三天未发货，客服电话打不通。",
    "questions": [
      {
        "id": "intent",
        "type": "choice",
        "question": "这条工单属于哪个类别？",
        "options": ["账务", "软件缺陷", "售前咨询", "物流"]
      }
    ]
  }'
​

预期返回形态（示意值）：

# systemone_response.json —— 返回示意
{
  "results": [
    {
      "id": "intent",
      "type": "choice",
      "answer": "物流",
      "probabilities": {"物流": 0.58, "售前咨询": 0.17, "软件缺陷": 0.13, "账务": 0.12},
      "confidence": 0.58,
      "checkpoint": "laya-multilingual"
    }
  ]
}
​

字段语义与第 1.2 节完全同构：answer 消费决策、probabilities 消费分布、confidence 留给第 7 章门控、checkpoint 记录路由归属。从 SDK 搬到 HTTP，变的只是传输层，没变的是读返回的顺序——先看谁在答，再看它笃定吗，最后看它说什么。

三、Jev 客户端改 baseUrl 直连

同线协议的直接红利：已经在用 Jev 官方客户端的系统，把服务地址从 Jev 云端换成本地 laya-serve，其余代码不动（官方口径：与 Jev 同线协议，客户端改 baseUrl 即可直连）：

# jev_client_point_to_laya.py —— Jev 客户端直连 laya-serve（写法示意，以两方官方文档为准）
# from jev_sdk import JevClient            # Jev 官方客户端（名称以其实方文档为准）
# client = JevClient(base_url="http://127.0.0.1:8000/v1")   # 只改这里

# result = client.decide(
#     state="工单：订单三天未发货，客服电话打不通。",
#     questions=[{"id": "intent", "type": "choice",
#                 "question": "属于哪个类别？",
#                 "options": ["账务", "软件缺陷", "售前咨询", "物流"]}],
# )
# print(result)
​

这个「改一行就能换后端」的性质，在架构上值三件事。混部：重要链路走 Jev、高频长尾走 laya，两边是同一种调用。灰度：新决策能力先在 laya 上影子验证，再切正式流量。降级：Jev 云端故障或预算收紧时，laya-serve 是现成的兜底后端——不是能力完全相等的兜底（高基数等场景 Jev 更强，官方承认），但形态兼容、切换成本接近零。

四、laya 侧的差异：多检查点路由

协议同线，行为有一处结构性差异：Jev 端点背后是一个托管的决策模型，laya-serve 背后是三个检查点加一个 Router。差异体现在两个位置。其一，请求侧可以表达检查点意图——交给 Router 自动分流（默认），或显式指定检查点（参数名以官方文档为准），对应第 2.2 节的两种模式。其二，返回侧多出路由痕迹——checkpoint 字段标明本次实际作答者，这在单模型形态的协议里没有对应物。

同一线协议，两种后端形态（示意）

   POST /v1/systemone
          │
   ┌──────┴──────────────────────┐
   ▼                             ▼
 Jev 云端                     laya-serve
 单一托管模型                  Router + 三检查点
 无路由概念                    可指定检查点/自动分流
                              返回带 checkpoint 字段
​

运维上的推论：laya-serve 的观测要按检查点分维度做——延迟、调用量、错配率各查各的（第 2.2 节的看数姿势平移到服务侧即可）；升级检查点时流量行为会跟着变，发布说明里要带上路由行为的变更。

五、上线前的服务自检

四步冒烟：健康检查通过；一条真实样本的 /v1/systemone 返回结构完整（四字段齐全）；把这条样本连发一小批看延迟稳定性（首几条偏慢属正常，检查点预热）；确认 checkpoint 字段符合预期辖区（中文样本不该落在英语检查点上，异常即回第 2.3 节排查）。CPU 部署时并发要保守起步：BERT 级前向在 CPU 上的并发能力有限，从小并发压起找拐点，或考虑多进程分片——具体形态以官方部署文档为准。

把四步固化成脚本，发布时一键执行：

# smoke_test.py —— 服务冒烟四步（写法示意）
import json
import urllib.request

BASE = "http://127.0.0.1:8000"

def get(path):
    with urllib.request.urlopen(BASE + path, timeout=5) as resp:
        return resp.status, resp.read().decode("utf-8")

def post(path, payload):
    req = urllib.request.Request(BASE + path, data=json.dumps(payload).encode(),
                                 headers={"Content-Type": "application/json"})
    with urllib.request.urlopen(req, timeout=10) as resp:
        return json.loads(resp.read().decode("utf-8"))

status, _ = get("/health")                       # 第一步：健康
body = {"state": "工单：订单三天未发货，客服电话打不通。",
        "questions": [{"id": "c", "type": "choice", "question": "属于哪类？",
                       "options": ["账务", "软件缺陷", "售前咨询", "物流"]}]}
r = post("/v1/systemone", body)["results"][0]    # 第二步：结构与字段
assert all(k in r for k in ("answer", "confidence", "checkpoint"))
assert r["checkpoint"] != "laya"                 # 第三步：中文样本的辖区检查
print("smoke ok:", r["answer"], r["checkpoint"])
​

冒烟通过只是「能跑」，能跑之后还要约定「跑不动时怎么办」——错误处理契约要与调用方提前写死：

本节要点回顾

• laya-serve 是官方自带的 FastAPI 服务（官方口径）；启动后先过健康检查，再压流量。
• /v1/systemone 与 Jev 同线协议：官方客户端改 baseUrl 直连；返回字段与 SDK 同构。
• 同线协议的红利：混部、灰度、降级三件事的成本都接近零。
• laya 侧差异：请求可表达检查点意图，返回带 checkpoint 字段；观测按检查点分维度做。
• 上线自检四步：健康、结构、延迟、辖区。

裸服务跑通了，接下来把它装进容器：一份 Dockerfile 钉死环境，健康检查与资源限额让它在 CPU 机器上安分守己，模型预下载让镜像启动即可用——下一节处理交付问题。