koach 开发者文档

koach 把 Keep 的运动健康能力拆成了可以按需采购的三层。这份文档只覆盖能通过 API 直接调用的部分 —— L1 模型与 L2 Agent 工厂。L3 的场景与用户属于商务合作范畴，不通过公开接口开放，详见官网说明。

想先跑起来看看效果

沙箱环境不需要签合同，用测试密钥就能调，每个账号有 500 万 token 的免费额度，足够完成一轮完整的技术验证。直接看快速开始。

能力地图

两层能力可以单独用，也可以叠起来用。多数客户的路径是：先用 L1 验证模型在自己业务口径下的效果和成本，再用 L2 把它组装成产品。

对话与向量

Keepace 运动健康大模型。OpenAI 兼容的 chat/completions 与 embeddings，换个 base_url 和密钥就能接。

微调与评测

用你自己的数据做 SFT / LoRA，并用运动健康领域评测集验收效果，而不是看通用榜单分数。

Skill 组件

训练计划生成、动作识别、饮食识别、数据解读、语音陪跑。 Keep 的底层能力，像调用函数一样组装。

Agent 与记忆

多轮编排、工具调用与可观测性开箱即用，内置记忆大脑，让 Agent 记住用户的习惯与身体状况。

接入信息

所有接口共用一套鉴权与错误约定。三种交付形态的差别只在 base URL：

形态	Base URL	适用
沙箱	`https://api-sandbox.koach.ai/v1`	技术验证、联调。有免费额度，数据不用于任何训练，30 天后清理
公有 API	`https://api.koach.ai/v1`	生产环境。按 token 阶梯计价，用量越大单价越低
私有化	`https://{your-host}/v1`	部署在客户自有环境。接口与参数完全一致，推理数据不出域

接口路径、请求体与响应结构在三种形态下完全一致。也就是说， 沙箱里调通的代码，切到私有化只需要改一个 base URL，不需要重写。

与 OpenAI SDK 的兼容性

L1 的对话与向量接口沿用了 OpenAI 的请求与响应结构，你可以直接用官方 SDK，只替换 base_url 和 api_key：

from openai import OpenAI

    client = OpenAI(
        api_key="sk-test-••••••••",
        base_url="https://api-sandbox.koach.ai/v1",
    )

    resp = client.chat.completions.create(
        model="keepace-pro",
        messages=[
            {"role": "system", "content": "你是一名持证运动康复教练。"},
            {"role": "user",   "content": "跑完 10 公里后膝盖外侧疼，怎么处理？"},
        ],
    )
    print(resp.choices[0].message.content)

import OpenAI from "openai";

    const client = new OpenAI({
      apiKey: "sk-test-••••••••",
      baseURL: "https://api-sandbox.koach.ai/v1",
    });

    const resp = await client.chat.completions.create({
      model: "keepace-pro",
      messages: [
        { role: "system", content: "你是一名持证运动康复教练。" },
        { role: "user",   content: "跑完 10 公里后膝盖外侧疼，怎么处理？" },
      ],
    });
    console.log(resp.choices[0].message.content);

curl https://api-sandbox.koach.ai/v1/chat/completions \
      -H "Authorization: Bearer $KOACH_API_KEY" \
      -H "Content-Type: application/json" \
      -d '{
        "model": "keepace-pro",
        "messages": [
          {"role": "system", "content": "你是一名持证运动康复教练。"},
          {"role": "user",   "content": "跑完 10 公里后膝盖外侧疼，怎么处理？"}
        ]
      }'

在此之上我们加了几个运动健康场景专用的扩展字段，都以 koach_ 前缀命名，不传时行为与标准 OpenAI 接口一致。详见扩展参数。

L2 的接口不是 OpenAI 兼容的

Skill 调用、Agent 编排和记忆大脑是 koach 自己的设计，没有对应的开源规范可循。这部分需要用我们的 SDK 或直接发 HTTP 请求。

建议的验证路径

这是多数客户实际走过的顺序，从零到能进内部评审大约需要 4 到 6 周。

跑通一次调用，确认接口没问题

用沙箱密钥发一个 chat 请求。目标只是排除网络、鉴权、SDK 版本这类环境问题，半小时以内应该完成。

用你自己的真实问题测专业度

准备 30 到 50 条业务里真实出现过的用户提问，对比 keepace 与你当前在用的通用模型。重点看损伤禁忌、训练处方这类需要专业判断的问题，通用模型在这里最容易说外行话。

算成本账

用同一批请求统计两边的 token 消耗与单价，换算成你的单用户月成本。这一步往往比效果对比更能决定项目能不能立项。

接一到两个 Skill，看能不能省掉自研

挑一个你原本打算自己做的能力（比如训练计划生成或数据解读），用 Skill 直接替换，评估节省的工程量。

用领域评测集产出可进评审会的报告

把前面的对比跑成结构化的评测任务，输出带统计口径和失败案例的报告。法务和风控要看的是这个，不是 Demo。

SDK 与工具

语言	安装	说明
Python	`pip install koach`	覆盖 L1 与 L2 全部接口，含流式与重试
Node.js	`npm i @koach/sdk`	同上，提供完整 TypeScript 类型
Java	`com.koach:koach-sdk`	仅 L1，L2 需直接发 HTTP 请求
其他	—	接口是标准 REST + SSE，任何能发 HTTP 请求的语言都可以接

遇到问题

沙箱阶段的技术问题走工单，一个工作日内响应。进入 POC 之后我们会拉一个专属技术群， Keep 这边的 FDE 前置工程师直接在群里跟进 —— 这是 L2 的标准交付内容之一，不额外收费。