> ## Documentation Index
> Fetch the complete documentation index at: https://docs.hyperframes-zh.cn/llms.txt
> Use this file to discover all available pages before exploring further.
# Lambda 上的模板
> 使用 --variables 和 lambda render-batch 动词在 AWS Lambda 上大规模渲染个性化模板视频。
HyperFrames 模板是采用输入变量（名称、颜色、图表负载、CTA URL）的组合，并生成由这些值参数化的最终渲染。将模板与已部署的 Lambda 堆栈和 `lambda render-batch` 配对，您可以通过一次 CLI 调用获得大规模个性化视频：
```bash theme={null}
hyperframes lambda render-batch ./my-template \
--batch ./users.jsonl \
--width 1920 --height 1080
```
本指南将介绍完整的循环：在组合上声明变量，使用 `hyperframes render` 进行本地迭代，部署到 Lambda 一次，然后从批处理文件中扇出 N 个渲染。相同的流程还通过 `lambda render --variables` 驱动单个个性化渲染，并通过 `renderToLambda({ variables })` 驱动程序化批次。
```mermaid theme={null}
flowchart LR
A["Local iteration
hyperframes render --variables"] --> B["Deploy stack
hyperframes lambda deploy"]
B --> C["Upload site once
hyperframes lambda sites create"]
C --> D["Fan out renders
hyperframes lambda render-batch"]
D --> E["N personalised videos
in S3"]
```
## 什么是模板
模板只是一个 HyperFrames 组合，其顶级 HTML 元素声明一个 `data-composition-variables` 属性，列出它接受的变量。该组合通过 `window.__hyperframes.getVariables()` 读取运行时值。
```html theme={null}
Welcome template
Welcome
![]()
```
运行时助手公开为全局 — `window.__hyperframes.getVariables()` — 而不是可获取的模块。使用普通的 `
```
同样的约束也适用于 Remotion 的 `inputProps` — 如果您从 `@remotion/lambda` 迁移，您的有效负载应该已经采用这种方式构建。
如果您的类型数据有效负载确实超过 256 KiB（例如，每次渲染的长结构化记录，没有媒体），[提交问题](https://github.com/heygen-com/hyperframes/issues/new) — 通过 S3 托管的变量文件有一条干净的路径，但我们希望在设计 API 之前看到真正的需求。
## 成本和规模
每个个性化渲染都是一次 Step Functions 执行 + N 次 Lambda 块调用。在默认设置（`chunkSize: 240`、`maxParallelChunks: 16`）下，5 秒 30fps 合成为 1 个块； 60 秒的作品大约有 8 个块。
成本旋钮：
* **`--max-parallel-chunks`**：每次渲染，默认 16。较小的合成不会扇出超过 `ceil(totalFrames / chunkSize)`。较高的值需要更多的 Lambda 调用，但完成速度更快。
* **Lambda 保留并发** (`lambda deploy --concurrency=`)：限制渲染函数可以并行运行的 Lambda 调用数量。同一 AWS 账户中的其他工作负载共享相同的账户级并发池（默认情况下，大多数区域约为 1000 个），因此保留并发性可防止渲染函数耗尽它们，反之亦然。
* **`render-batch --max-concurrent`**：协调器端。限制同时运行的 `StartExecution` 调用数量 - 与 Lambda 并发上限不同，后者位于块调用层的下一级。 CLI 无法强制执行 Lambda 的账户限制；它只能避免创建多余的 Step Functions 执行队列。
* **Lambda 内存** (`lambda deploy --memory`)：默认 10 240 MB（最大）。更高的内存可以购买更快的 Chrome 捕获 + 每个块更多的 vCPU；较低的内存可以节省成本，但在繁重的合成上可能会面临 `15 min` 超时的风险。
每个 Step Functions 执行都会扇出到 \~`maxParallelChunks` Lambda 调用。因此，如果部署的预留并发数为 8 并且 `maxParallelChunks` 保持默认值 16，即使是单个渲染也会受到限制 - 在运行大批量之前提高部署并发数。
对于小批量（\< 100 个条目），默认 `--max-concurrent 50` 就可以了。对于大批量 (> 1000)，一个有用的起点是 `--max-concurrent ≈ floor(reservedConcurrency / maxParallelChunks)`，因此每个正在运行的渲染都会获得其完整的块扇出预算；批处理动词不强制执行此操作，它只是选择标志值的指导。
进程内与分布式交叉：对于大约 30 秒内的单个渲染，进程内渲染器 (`hyperframes render`) 在延迟方面获胜，因为每个块没有 S3 往返。分布式渲染在大约 60 秒内或当您需要个性化批次时获胜 - 这就是此表面存在的全部原因。 （第 7 阶段的小渲染快捷方式落地后，将缩小短渲染的间隙。）
## 从 @remotion/lambda inputProps 迁移
Remotion 的 `inputProps` API 和 HyperFrames 的 `variables` 是同构的 — 两者都是作为渲染时覆盖在声明的组合默认值之上注入的 JSON 对象。映射是机械的：
| 远程 | HyperFrames |
| ------------------------------------- | ------------------------------------------------------------------- |
| `Composition.defaultProps` | 根 HTML 元素上的 `data-composition-variables` 声明 |
| `useCurrentFrame()` + `props.` | `window.__hyperframes.getVariables().`（在 DOMContentLoaded 上读取一次） |
| `renderMediaOnLambda({ inputProps })` | `renderToLambda({ config: { variables } })` |
| Lambda inputProps 256 KiB 上限 | Step Functions 执行输入 256 KiB 上限 |
| 大型媒体的 inputProps URL 模式 | 相同的约定 - URL 引用，而不是内联字节 |
Remotion 的 `inputProps` 具有相同的 256 KiB 约束和相同的“URL 您的资产”约定，因此工作 `inputProps` 管道的迁移是简单的 CLI/SDK 交换，而不是有效负载重塑。
## 接下来是什么
* **小批量原语**：HTML 表单输入以及 JSONL。如果您觉得这有用，请打开一个问题。
* **从 `data-composition-variables`** 生成的 TypeScript 类型：`hyperframes types generate ` 已草拟，可能会登陆 v1.5；它会让 SDK 调用者 `import type { Variables } from "./template/variables"` 进行自动完成+类型检查。
* **HDR 模板支持**：HDR mp4 目前被分布式模式拒绝（仅限进程内）。下一个 v1.5 项目是为分布式渲染解锁 HDR，以便模板可以生成广色域输出。
如果您的模板管道遇到了文档未涵盖的问题，[在 GitHub 上提交问题](https://github.com/heygen-com/hyperframes/issues/new) — 批处理表面是新的，并且其反馈循环很短。