Lavender1 · Sep 20, 2026
diff --git a/docs/en/api/index.md b/docs/en/api/index.md
@@ -4,11 +4,11 @@ Import application APIs from `rayorch`:
 
 | API | Purpose |
 | --- | --- |
-| `Pipeline` | declare a static dataflow in `forward()` |
+| `Pipeline` | declare a static dataflow in `forward()` and execute one finite input with `pipeline.run(...)` |
 | `RayModule` | declare a UDF, constructor args, outputs, and resources |
 | `function` | adapt a callable into a stateless `RayModule` |
 | `F.expand`, `F.filter`, `F.broadcast`, `F.reduce` | declare cardinality and lineage |
-| `run` | execute one finite input with automatic cleanup |
+| `run` | equivalent functional form: `rayorch.run(pipeline, ...)` |
 | `Executor` | reuse persistent actor pools across runs |
 | `RunResult`, `OutputIssue`, `ItemOutcome` | inspect outputs and run metrics |
 | `RecordFailure`, `GroupFailure` | return explicit business failures from UDFs |

diff --git a/docs/en/concepts/results-failures.md b/docs/en/concepts/results-failures.md
@@ -5,7 +5,7 @@
 `RunResult.outputs` preserves the Pipeline output structure. Successful business values are returned unchanged, including `None` and empty lists.
 
 ```python
-result = ro.run(MyPipeline(), inputs)
+result = MyPipeline().run(inputs)
 print(result.outputs)
 print(result.elapsed_s)
 print(result.rpc_count)

diff --git a/docs/en/distributed/index.md b/docs/en/distributed/index.md
@@ -16,7 +16,7 @@ RayOrch
   └─ reconstruct results and reports
 ```
 
-Connect to an existing cluster with `address="auto"` in `rayorch.run()` or `Executor`. Ray places each persistent actor according to the options declared on its Call.
+Connect to an existing cluster with `address="auto"` in `pipeline.run()` or `Executor`. The equivalent functional form `rayorch.run(pipeline, ...)` remains available. Ray places each persistent actor according to the options declared on its Call.
 
 ## Multi-node contract
 

diff --git a/docs/en/guide/fan-out-and-reduce.md b/docs/en/guide/fan-out-and-reduce.md
@@ -71,7 +71,7 @@ if __name__ == "__main__":
         {"name": "guide", "pages": 2},
         {"name": "paper", "pages": 3},
     ]
-    result = ro.run(DocumentPipeline(), inputs)
+    result = DocumentPipeline().run(inputs)
     print(result.outputs)
 ```
 

diff --git a/docs/en/guide/first-pipeline.md b/docs/en/guide/first-pipeline.md
@@ -42,7 +42,8 @@ class AddTwo(ro.Pipeline):
 
 
 if __name__ == "__main__":
-    result = ro.run(AddTwo(), [1, 2, 3])
+    pipeline = AddTwo()
+    result = pipeline.run([1, 2, 3])
     print(result.outputs)
 ```
 
@@ -109,10 +110,11 @@ def forward(self, values):
 
 `forward()` builds a static graph; it does not execute `AddOne.run()` at this point. `values` and `after_first` are symbolic `Port` values expressing that the second stage depends on the first.
 
-### `ro.run()`: compile, start, execute, and collect
+### `pipeline.run()`: compile, start, execute, and collect
 
 ```python
-result = ro.run(AddTwo(), [1, 2, 3])
+pipeline = AddTwo()
+result = pipeline.run([1, 2, 3])
 ```
 
 This call:
@@ -143,8 +145,8 @@ RayOrch creates two actors for that stage and shares ready work across them. Mak
 ### Process more input
 
 ```python
-result = ro.run(
-    AddTwo(),
+pipeline = AddTwo()
+result = pipeline.run(
     list(range(100)),
     input_batch_size=20,
     max_active_input_batches=2,
@@ -161,7 +163,7 @@ Keep the defaults at first; tune them independently as the workload grows.
 
 ## 5. Reuse actors across several runs
 
-`ro.run()` is convenient for one finite input. If model startup is expensive and the same Pipeline runs repeatedly, use `Executor` directly:
+`pipeline.run()` is convenient for one finite input and closes its temporary Executor afterward. The equivalent functional form `ro.run(pipeline, inputs)` remains available. If model startup is expensive and the same Pipeline runs repeatedly, use `Executor` directly:
 
 ```python
 with ro.Executor(AddTwo()) as executor:
@@ -181,6 +183,6 @@ A first Pipeline only needs:
 - a batched UDF with `run()`;
 - a `Pipeline` that declares stages with `RayModule`;
 - a `forward()` method that describes dependencies;
-- one `ro.run()` call with source data.
+- one `pipeline.run()` call with source data.
 
 The next chapter introduces RayOrch's central dataflow operation: [fan one input out into children and reduce them in order](fan-out-and-reduce.md).
diff --git a/docs/en/guide/index.md b/docs/en/guide/index.md
@@ -48,7 +48,7 @@ class MyPipeline(ro.Pipeline):
         return self.add(values)
 
 
-result = ro.run(MyPipeline(), [1, 2, 3])
+result = MyPipeline().run([1, 2, 3])
 print(result.outputs)  # [2, 3, 4]
 ```
 

diff --git a/docs/en/guide/installation.md b/docs/en/guide/installation.md
@@ -65,7 +65,7 @@ class Check(ro.Pipeline):
 
 
 if __name__ == "__main__":
-    result = ro.run(Check(), ["Ray", "Orch"])
+    result = Check().run(["Ray", "Orch"])
     print(result.outputs)
 ```
 

diff --git a/docs/en/guide/multi-node.md b/docs/en/guide/multi-node.md
@@ -79,8 +79,8 @@ class GpuPool(ro.Pipeline):
 
 
 if __name__ == "__main__":
-    result = ro.run(
-        GpuPool(),
+    pipeline = GpuPool()
+    result = pipeline.run(
         ["left", "right"],
         address="auto",
     )
@@ -112,8 +112,7 @@ self.infer = ro.RayModule(Infer).ray_options(
 ```
 
 ```python
-result = ro.run(
-    pipeline,
+result = pipeline.run(
     inputs,
     address="auto",
     input_batch_size=24,

diff --git a/docs/zh/api/index.md b/docs/zh/api/index.md
@@ -4,7 +4,7 @@
 
 | API | 用途 |
 | --- | --- |
-| `Pipeline` | 在 `forward()` 中声明静态数据流 |
+| `Pipeline` | 在 `forward()` 中声明静态数据流，并通过 `pipeline.run(...)` 执行一次有限输入 |
 | `RayModule` | 声明 UDF、构造参数、输出数和资源 |
 | `function` | 把 callable 转为无状态 `RayModule` |
 | `F.expand/filter/broadcast/reduce` | 声明基数和血缘 |

diff --git a/docs/zh/concepts/results-failures.md b/docs/zh/concepts/results-failures.md
@@ -5,7 +5,7 @@
 `RunResult.outputs` 保持 Pipeline 声明的输出结构。成功业务值原样返回，包括 `None` 和空列表。
 
 ```python
-result = ro.run(MyPipeline(), inputs)
+result = MyPipeline().run(inputs)
 print(result.outputs)
 print(result.elapsed_s)
 print(result.rpc_count)

diff --git a/docs/zh/distributed/index.md b/docs/zh/distributed/index.md
@@ -16,7 +16,7 @@ RayOrch
   └─ 重建结果和报告
 ```
 
-在 `rayorch.run()` 或 `Executor` 中传入 `address="auto"` 即可连接现有集群。Ray 根据每个 Call 声明的资源选项放置常驻 Actor。
+在 `pipeline.run()` 或 `Executor` 中传入 `address="auto"` 即可连接现有集群；等价的函数式入口 `rayorch.run(pipeline, ...)` 仍然保留。Ray 根据每个 Call 声明的资源选项放置常驻 Actor。
 
 ## 多机运行契约
 

diff --git a/docs/zh/guide/fan-out-and-reduce.md b/docs/zh/guide/fan-out-and-reduce.md
@@ -71,7 +71,7 @@ if __name__ == "__main__":
         {"name": "guide", "pages": 2},
         {"name": "paper", "pages": 3},
     ]
-    result = ro.run(DocumentPipeline(), inputs)
+    result = DocumentPipeline().run(inputs)
     print(result.outputs)
 ```
 

diff --git a/docs/zh/guide/first-pipeline.md b/docs/zh/guide/first-pipeline.md
@@ -42,7 +42,8 @@ class AddTwo(ro.Pipeline):
 
 
 if __name__ == "__main__":
-    result = ro.run(AddTwo(), [1, 2, 3])
+    pipeline = AddTwo()
+    result = pipeline.run([1, 2, 3])
     print(result.outputs)
 ```
 
@@ -111,10 +112,11 @@ def forward(self, values):
 
 `forward()` 构建的是静态图，不会在这里真正执行 `AddOne.run()`。其中的 `values` 和 `after_first` 是符号化的 `Port`，用来表达“第二个阶段依赖第一个阶段的输出”。
 
-### `ro.run()`：编译、启动和收集结果
+### `pipeline.run()`：编译、启动和收集结果
 
 ```python
-result = ro.run(AddTwo(), [1, 2, 3])
+pipeline = AddTwo()
+result = pipeline.run([1, 2, 3])
 ```
 
 一次调用会完成：
@@ -145,8 +147,8 @@ RayOrch 会为该阶段创建两个 Actor，共享它的就绪任务。确保本
 ### 处理更多输入
 
 ```python
-result = ro.run(
-    AddTwo(),
+pipeline = AddTwo()
+result = pipeline.run(
     list(range(100)),
     input_batch_size=20,
     max_active_input_batches=2,
@@ -163,7 +165,7 @@ result = ro.run(
 
 ## 5. 需要多次运行时复用 Actor
 
-`ro.run()` 适合一次有限输入。如果模型加载很慢，并且同一 Pipeline 要连续执行多次，可以直接使用 `Executor`：
+`pipeline.run()` 适合一次有限输入，并会在结束后关闭临时 Executor；等价的函数式入口 `ro.run(pipeline, inputs)` 仍然保留。如果模型加载很慢，并且同一 Pipeline 要连续执行多次，可以直接使用 `Executor`：
 
 ```python
 with ro.Executor(AddTwo()) as executor:
@@ -183,6 +185,6 @@ print(second.outputs)  # [12, 22]
 - 一个带 `run()` 的批量 UDF；
 - 一个用 `RayModule` 声明阶段的 `Pipeline`；
 - 一个 `forward()` 描述依赖；
-- 一次 `ro.run()` 提交输入。
+- 一次 `pipeline.run()` 提交输入。
 
 下一章会加入 RayOrch 最关键的数据流能力：[一个输入展开成多个子项，再按原顺序聚合](fan-out-and-reduce.md)。
diff --git a/docs/zh/guide/index.md b/docs/zh/guide/index.md
@@ -48,7 +48,7 @@ class MyPipeline(ro.Pipeline):
         return self.add(values)
 
 
-result = ro.run(MyPipeline(), [1, 2, 3])
+result = MyPipeline().run([1, 2, 3])
 print(result.outputs)  # [2, 3, 4]
 ```
 

diff --git a/docs/zh/guide/installation.md b/docs/zh/guide/installation.md
@@ -65,7 +65,7 @@ class Check(ro.Pipeline):
 
 
 if __name__ == "__main__":
-    result = ro.run(Check(), ["Ray", "Orch"])
+    result = Check().run(["Ray", "Orch"])
     print(result.outputs)
 ```
 

diff --git a/docs/zh/guide/multi-node.md b/docs/zh/guide/multi-node.md
@@ -79,8 +79,8 @@ class GpuPool(ro.Pipeline):
 
 
 if __name__ == "__main__":
-    result = ro.run(
-        GpuPool(),
+    pipeline = GpuPool()
+    result = pipeline.run(
         ["left", "right"],
         address="auto",
     )
@@ -112,8 +112,7 @@ self.infer = ro.RayModule(Infer).ray_options(
 ```
 
 ```python
-result = ro.run(
-    pipeline,
+result = pipeline.run(
     inputs,
     address="auto",
     input_batch_size=24,