# Cookbook Valen 完整应用教程：可运行代码、样例输入和真实模型输出，按要解决的目标分组。每篇都遵循同一个分工：Valen 回答带类型的问题，代码把回答变成决策。 Interactive content: [open the web page](https://valen-team.github.io/zh-Hans/cookbook/). ## 不用 API key 也能运行 每篇调用远程服务的教程都附带 `caches/.json`，里面是样例输入的真实回答，按模型和请求内容索引。下载后所有教程都能离线运行，输出与页面一致。改动问题或输入后，运行器会对新请求调用模型并记录回答。 ```bash curl -fLO https://valen-team.github.io/cookbook/valen-cookbook.zip python -m zipfile -e valen-cookbook.zip . cd valen-cookbook python rerank.py # 使用录制的回答，无需 key python rerank.py --replay off # 每次都调用模型 ``` `--replay only` 只使用录制的回答，官网构建时就用这种方式检查每篇教程。 ## 分工与复现 [API 文档](/zh-Hans/docs/valen/api.md)维护协议、字段、错误和最短调用；[部署文档](/zh-Hans/docs/valen/choosing.md)维护安装与后端配置；Cookbook 维护完整应用。准备设置自动处理与人工复核规则？先看[发布模型实测](/docs/valen/reliability.md)，再按[校准与自动处理教程](/docs/valen/calibration.md)验证自己的数据。 [验证、性能与版本范围](./validation/) · [旧内容迁移表](./migration/) · 下载脚本、样例数据与录制的回答 # API 入门 本教程迁移旧 API Notebook：发送修改收货地址的文本、识别图片中的动物群体、判断视频中间帧里的酱汁颜色。输出包含命名答案和真实抽帧位置。完整业务流程分别在后面的三个应用教程维护。 HTTP 客户端使用 **Decisions**。图片以 data URL 传入；视频示例先抽帧再发送图片，不代表托管 API 支持直接视频推理。仅在所选服务需要认证时设置 `VALEN_API_KEY`。 ## 安装与输入 Python 3.11+。先下载小型源文件包并解压，然后安装所需依赖： ```bash curl -fLO https://valen-team.github.io/cookbook/valen-cookbook.zip python -m zipfile -e valen-cookbook.zip . cd valen-cookbook python -m pip install -r requirements.txt ``` 明确执行后才获取以下小素材（图片约 58 KB，视频约 395 KB）；也可将有权使用的同名文件放在 `--asset-dir` 指定目录。 ```bash curl -fL https://raw.githubusercontent.com/Valen-Team/Valen/main/assets/cookbook/sheep.jpg -o sheep.jpg curl -fL https://raw.githubusercontent.com/Valen-Team/Valen/main/assets/cookbook/momos.mp4 -o momos.mp4 ``` Interactive content: [open the web page](https://valen-team.github.io/zh-Hans/cookbook/api-quickstart/). ## 运行 `caches/api_quickstart.json` 中录制的回答让脚本无需 API key 即可运行；加 `--replay off` 则改为调用[免费托管 API](/zh-Hans/docs/valen/api.md)。 ```bash python api_quickstart.py --asset-dir . --output result.json python api_quickstart.py --replay off --model valen-2b --asset-dir . --output result.json # 改用已有的本地 HTTP 部署： python api_quickstart.py --replay off --base-url http://127.0.0.1:8000/v1 --model valen --asset-dir . --output result.json ``` 本地 ONNX 也可直接运行：把参数改为 `--backend onnx --model /path/to/Valen-0.8B-ONNX`，并先安装 `valen-sdk[onnx,video]==0.2.0`。GGUF 服务通过 `--backend remote` 接入；不能把 GGUF 文件传给 `Valen.local`。 ## 完整可执行代码 `api_quickstart.py`: ```python """API basics: text, one image and a sampled video frame. Apache-2.0.""" from common import client, emit, image_bytes, image_input, middle_frame, parser, request, samples def main(): args = parser(__doc__).parse_args() data = samples() with client(args) as predict: text = request(predict, data["ticket"]["text"], data["ticket"]["questions"]) image = request(predict, image_input(image_bytes(args.asset_dir / data["product"]["image"])), [data["product"]["question"]]) payload, sampling = middle_frame(args.asset_dir / data["video"]["path"]) video_frame = request(predict, image_input(payload), [data["video"]["question"]]) emit({"text": text, "image": image, "video_frame": video_frame, "sampling": sampling}, args) if __name__ == "__main__": main() ``` 共享运行器与 `samples.json` 已包含在下载包中，与网页展示内容使用同一个维护源。

common.py

`common.py`: ```python """Shared cookbook runner. Apache-2.0. No implicit model or media downloads.""" import argparse import base64 from contextlib import ExitStack, contextmanager import datetime import hashlib import json import math import os from pathlib import Path import sys HERE = Path(__file__).resolve().parent CACHES = HERE / "caches" def samples(): return json.loads((HERE / "samples.json").read_text()) def parser(description): p = argparse.ArgumentParser(description=description) p.add_argument("--backend", choices=["remote", "onnx", "native"], default="remote") p.add_argument("--base-url", default=os.environ.get("VALEN_BASE_URL", "https://api.valen-team.workers.dev/v1")) p.add_argument("--model", default=os.environ.get("VALEN_MODEL")) p.add_argument("--threads", type=int, default=4) p.add_argument("--asset-dir", type=Path, default=Path(".")) p.add_argument("--output", type=Path) p.add_argument("--replay", choices=["auto", "only", "off"], default="auto", help="auto: reuse recorded answers and record new ones; only: recorded answers only; " "off: always call the model") return p @contextmanager def client(args): """Answers for remote requests are recorded in caches/