Jina 编排实战:如何用 `uses` 定义与配置 Executor(本地与外部 Executor 全指南)

原创2026-09-19 19:48:431,384 阅读
文章标签:后端微服务人工智能模型推理服务

Jina 编排实战:如何用 uses 定义与配置 Executor(本地与外部 Executor 全指南)

在 Jina 的多模态 AI 编排体系中,Executor 是承载具体处理逻辑(编码、索引、搜索、重排等)的最小执行单元。本篇指南围绕 Jina 编排(Orchestration)中"如何把 Executor 挂载到 Deployment 或 Flow"这一核心命题展开,完整讲解 uses 的六种取值形式、uses_with / uses_metas / uses_requests / workspace 等配置覆盖手段,以及如何通过 external=True 接入由其他编排管理的共享 Executor(含 TLS 与 gRPC 认证元数据)。读完本文,你将能够熟练地把任意形态的 Executor 接入自己的编排拓扑,并掌握在本地开发、Executor Hub 与 JCloud 不同环境下的正确姿势。

一、用 uses 定义 Executor 类型

一个 {class}~jina.Executor的类型由uses关键字决定。无论是独立的 Deployment 还是 Flow 中的一个节点,传入uses` 即可告诉编排层"这里跑的是哪个 Executor":

```python
from jina import Deployment

dep = Deployment(uses=MyExec)
```
```python
from jina import Flow

f = Flow().add(uses=MyExec)
```

uses 的六种取值形式

uses 并不仅仅接受类对象,根据取值不同,Jina 会采用完全不同的加载策略。下表汇总了本地开发(Local Dev)与 JCloud 两种场景下的支持情况:

Local Dev JCloud uses=... 说明
✅ ❌ ExecutorClass 使用内联上下文(inline context)中的 ExecutorClass。
✅ ❌ 'my.py_modules.ExecutorClass' 使用 my.py_modules 中的 ExecutorClass(配合 py_modules 参数导入)。
✅ ✅ 'executor-config.yml' 使用由 Executor YAML 接口(见 docs/concepts/orchestration/yaml-spec.md)定义的 YAML 文件加载 Executor。
✅ ❌ 'jinaai://jina-ai/TransformerTorchEncoder/' 以 Python 源码形式从 Executor Hub 拉取 Executor。
✅ ✅ 'jinaai+docker://jina-ai/TransformerTorchEncoder' 以 Docker 容器形式从 Executor Hub 运行 Executor。
✅ ❌ 'docker://sentence-encoder' 使用预构建的 Docker 容器作为 Executor。

从上表可以提炼出两条实用经验:

  • JCloud 只支持两种形式:YAML 文件('executor-config.yml')与 Hub 的 Docker 形式('jinaai+docker://...')。这是因为 JCloud 出于安全考虑与便于本地调试的定位,不允许直接运行来自内联上下文或任意 Python 模块的代码;需要打包为镜像或声明式配置才能云端化部署。
  • 本地开发最灵活:直接传类对象、传模块路径、甚至传一个 dict 配置都是合法的。从 jina/orchestrate/flow/base.py 中 Flow.add() 的参数文档可以看到,uses 的合法取值还包括"以 ! 或 jtype: 开头的 YAML 字符串字面量、JSON 配置字符串、具有 .read() 接口的文本流"等。

从同一目录加载多个 Executor

当多个 Executor 散落在同一目录时,不必为每个 Executor 重复书写父目录路径,可以通过 extra_search_paths 配置公共搜索路径,让 Jina 自动在此路径下寻找 uses 中引用的资源:

.
├── app
│   └── ▶ main.py
└── executor
    ├── config1.yml
    ├── config2.yml
    └── my_executor.py
dep = Deployment(extra_search_paths=['../executor']).add(uses='config1.yml')) # Deployment
f = Flow(extra_search_paths=['../executor']).add(uses='config1.yml').add(uses='config2.yml') # Flow

这一机制在源码层同样得到印证:Worker 运行时加载 Executor 时会把 extra_search_paths 显式传给 BaseExecutor.load_config(见 jina/serve/runtimes/worker/request_handling.py 的 _load_executor 方法),从而保证 YAML 文件与依赖的 Python 模块都能被正确解析。

二、添加 Executor 时覆盖其配置

将 Executor 挂载到编排对象时,可以同步设置或覆盖 Executor 的配置。以下示例同时展示了 Deployment 与 Flow 两种 API 的等价写法:

```python
from jina import Deployment

dep = Deployment(
    uses='MyExecutor',
    py_modules=["executor.py"],
    uses_with={"parameter_1": "foo", "parameter_2": "bar"},
    uses_metas={
        "name": "MyExecutor",
        "description": "MyExecutor does a thing to the stuff in your Documents",
    },
    uses_requests={"/index": "my_index", "/search": "my_search", "/random": "foo"},
    workspace="some_custom_path",
)

with dep:
    ...
```
```python
from jina import Flow

f = Flow().add(
    uses='MyExecutor',
    py_modules=["executor.py"],
    uses_with={"parameter_1": "foo", "parameter_2": "bar"},
    uses_metas={
        "name": "MyExecutor",
        "description": "MyExecutor does a thing to the stuff in your Documents",
    },
    uses_requests={"/index": "my_index", "/search": "my_search", "/random": "foo"},
    workspace="some_custom_path",
)

with f:
    ...
```

各参数的语义如下:

  • py_modules:字符串列表,定义 Executor 的 Python 依赖模块。执行时 Worker 会先导入这些模块再加载 Executor(对应 jina/serve/runtimes/worker/request_handling.py 中 _load_executor 对 py_modules 的透传)。
  • uses_with:键值映射,对应 Executor __init__ 方法的参数(即 Executor 的 with 配置)。
  • uses_requests:键值映射,定义"端点 → 类方法"的绑定关系,用于覆盖 Executor 实现中默认的端点映射。
  • uses_metas:键值映射,覆盖 Executor 的部分内部属性,包含以下字段:
    • name:字符串,定义 Executor 名称;
    • description:字符串,定义 Executor 描述,会用于自动生成的 API 文档界面(如 Swagger UI)。
  • workspace:字符串,定义 Executor 的工作目录(用于各类 IO 操作)。

这些参数在 jina/orchestrate/flow/base.py 的 Flow.add() 签名(第 839-910 行)中全部可见:py_modules、uses_with、uses_metas、uses_requests、workspace 均为可选参数,此外还包含 uses_dynamic_batching(动态批处理覆盖)、uses_before / uses_after(分片前后的附加 Executor)等进阶项。对参数语义的完整说明可继续查阅 docs/concepts/orchestration/flow-args.md 与 docs/concepts/orchestration/deployment-args.md。

三、通过 uses_with 设置构造函数参数(with 配置)

with 配置指用户自定义的构造函数 kwargs。使用 uses_with 即可在添加 Executor 时设置或覆盖这些参数,而未在字典中出现的参数保持其默认值。

```python
from jina import Executor, requests, Deployment


class MyExecutor(Executor):
    def __init__(self, param1=1, param2=2, param3=3, *args, **kwargs):
        super().__init__(*args, **kwargs)
        self.param1 = param1
        self.param2 = param2
        self.param3 = param3

    @requests
    def foo(self, docs, **kwargs):
        print('param1:', self.param1)
        print('param2:', self.param2)
        print('param3:', self.param3)


dep = Deployment(uses=MyExecutor, uses_with={'param1': 10, 'param3': 30})

with dep:
    dep.post('/')
```
```text
      executor0@219662[L]:ready and listening
        gateway@219662[L]:ready and listening
           Deployment@219662[I]:🎉 Deployment is ready to use!
	🔗 Protocol: 		GRPC
	🏠 Local access:	0.0.0.0:32825
	🔒 Private network:	192.168.1.101:32825
	🌐 Public address:	197.28.82.165:32825
param1: 10
param2: 2
param3: 30
```
```python
from jina import Executor, requests, Flow


class MyExecutor(Executor):
    def __init__(self, param1=1, param2=2, param3=3, *args, **kwargs):
        super().__init__(*args, **kwargs)
        self.param1 = param1
        self.param2 = param2
        self.param3 = param3

    @requests
    def foo(self, docs, **kwargs):
        print('param1:', self.param1)
        print('param2:', self.param2)
        print('param3:', self.param3)


f = Flow().add(uses=MyExecutor, uses_with={'param1': 10, 'param3': 30})

with f:
    f.post('/')
```
```text
      executor0@219662[L]:ready and listening
        gateway@219662[L]:ready and listening
           Flow@219662[I]:🎉 Flow is ready to use!
	🔗 Protocol: 		GRPC
	🏠 Local access:	0.0.0.0:32825
	🔒 Private network:	192.168.1.101:32825
	🌐 Public address:	197.28.82.165:32825
param1: 10
param2: 2
param3: 30
```

运行输出清晰地展示了覆盖行为:param1 被覆盖为 10、param3 被覆盖为 30,而 param2 未被提及、保持了构造函数默认值 2。这正是"部分覆盖、其余回退默认"的 uses_with 语义。

四、通过 uses_requests 重绑定端点(requests 配置)

uses_requests 用于设置/覆盖 Executor 的 requests 配置,把方法绑定到自定义端点上。下面的代码演示了三种操作:

  • 将原本绑定在 /foo 的 foo() 方法,同时替换为绑定到 /non_foo 与 /alias_foo;
  • 为 bar() 新增 /bar 端点;
  • 注意:all_req() 方法绑定了除显式绑定到其他函数之外的所有端点,即 /non_foo、/alias_foo 和 /bar 之外的端点(在本例中为 /foo)。
```python
from jina import Executor, requests, Deployment


class MyExecutor(Executor):
    @requests
    def all_req(self, parameters, **kwargs):
        print(f'all req {parameters.get("recipient")}')

    @requests(on='/foo')
    def foo(self, parameters, **kwargs):
        print(f'foo {parameters.get("recipient")}')

    def bar(self, parameters, **kwargs):
        print(f'bar {parameters.get("recipient")}')


dep = Deployment(
    uses=MyExecutor,
    uses_requests={
        '/bar': 'bar',
        '/non_foo': 'foo',
        '/alias_foo': 'foo',
    },
)

with dep:
    dep.post('/bar', parameters={'recipient': 'bar()'})
    dep.post('/non_foo', parameters={'recipient': 'foo()'})
    dep.post('/foo', parameters={'recipient': 'all_req()'})
    dep.post('/alias_foo', parameters={'recipient': 'foo()'})
```

```text
      executor0@221058[L]:ready and listening
        gateway@221058[L]:ready and listening
           Deployment@221058[I]:🎉 Deployment is ready to use!
	🔗 Protocol: 		GRPC
	🏠 Local access:	0.0.0.0:36507
	🔒 Private network:	192.168.1.101:36507
	🌐 Public address:	197.28.82.165:36507
bar bar()
foo foo()
all req all_req()
foo foo()
```
```python
from jina import Executor, requests, Flow


class MyExecutor(Executor):
    @requests
    def all_req(self, parameters, **kwargs):
        print(f'all req {parameters.get("recipient")}')

    @requests(on='/foo')
    def foo(self, parameters, **kwargs):
        print(f'foo {parameters.get("recipient")}')

    def bar(self, parameters, **kwargs):
        print(f'bar {parameters.get("recipient")}')


f = Flow().add(
    uses=MyExecutor,
    uses_requests={
        '/bar': 'bar',
        '/non_foo': 'foo',
        '/alias_foo': 'foo',
    },
)
with f:
    f.post('/bar', parameters={'recipient': 'bar()'})
    f.post('/non_foo', parameters={'recipient': 'foo()'})
    f.post('/foo', parameters={'recipient': 'all_req()'})
    f.post('/alias_foo', parameters={'recipient': 'foo()'})
```

```text
      executor0@221058[L]:ready and listening
        gateway@221058[L]:ready and listening
           Flow@221058[I]:🎉 Flow is ready to use!
	🔗 Protocol: 		GRPC
	🏠 Local access:	0.0.0.0:36507
	🔒 Private network:	192.168.1.101:36507
	🌐 Public address:	197.28.82.165:36507
bar bar()
foo foo()
all req all_req()
foo foo()
```

输出按请求顺序验证了绑定结果:/bar 触发 bar()、/non_foo 与 /alias_foo 都触发 foo()、而未被显式绑定的 /foo 回落到默认的 all_req()(因为 @requests 装饰器默认绑定"其余所有端点")。这一机制让"一个方法多端点、端点多方法"的灵活路由成为可能,也是覆盖 Hub 上第三方 Executor 默认端点的标准手段。

五、通过 uses_metas 覆盖内部属性(metas 配置)

metas 是 Executor 的内部元信息。使用 uses_metas 可以设置/覆盖这些属性,例如把 Executor 实例的名称改为 different_name,随后在处理方法中通过 self.metas.name 读取:

```python
from jina import Executor, requests, Deployment


class MyExecutor(Executor):
    @requests
    def foo(self, docs, **kwargs):
        print(self.metas.name)


dep = Deployment(
    uses=MyExecutor,
    uses_metas={'name': 'different_name'},
)

with dep:
    dep.post('/')
```

```text
      executor0@219291[L]:ready and listening
        gateway@219291[L]:ready and listening
           Deployment@219291[I]:🎉 Deployment is ready to use!
	🔗 Protocol: 		GRPC
	🏠 Local access:	0.0.0.0:58827
	🔒 Private network:	192.168.1.101:58827
different_name
```
```python
from jina import Executor, requests, Flow


class MyExecutor(Executor):
    @requests
    def foo(self, docs, **kwargs):
        print(self.metas.name)


flow = Flow().add(
    uses=MyExecutor,
    uses_metas={'name': 'different_name'},
)
with flow as f:
    f.post('/')
```

```text
      executor0@219291[L]:ready and listening
        gateway@219291[L]:ready and listening
           Flow@219291[I]:🎉 Flow is ready to use!
	🔗 Protocol: 		GRPC
	🏠 Local access:	0.0.0.0:58827
	🔒 Private network:	192.168.1.101:58827
different_name
```

除了 name,uses_metas 通常还支持 description(用于自动文档 UI)等字段。从底层实现看,所有这些覆盖项最终都会随 Worker 运行时参数一起传递给 BaseExecutor.load_config(见 jina/serve/runtimes/worker/request_handling.py),从而在 Executor 实例化之前完成对 with、metas、requests 的三重注入——这也是 uses_with / uses_metas / uses_requests 三者能够以声明方式覆盖 Python 类实现中默认行为的原因。

六、使用外部 Executor(External Executors)

什么是外部 Executor

通常,一个编排(Orchestration)会自行启动并停止它拥有的 Executor。而外部 Executor 的所有权属于其他编排——它们可以驻留在任意机器上,生命周期由他人控制。

使用外部 Executor 的最大价值在于共享昂贵资源:例如无状态、GPU 加速的编码器(Encoder),如果每个编排都各自启动一份,会造成严重的资源浪费;通过外部 Executor 可以让多个编排复用同一份实例。

被"独立服务(Served)"与"共享(Shared)"的 Executor 都可以作为外部 Executor 接入编排。

接入外部 Executor

接入外部 Executor 时必须提供 host 与 port,并开启 external 标志:

```python
from jina import Deployment

Deployment(host='123.45.67.89', port=12345, external=True)

# 或合并写法

Deployment(host='123.45.67.89:12345', external=True)
```
```python
from jina import Flow

Flow().add(host='123.45.67.89', port=12345, external=True)

# 或合并写法

Flow().add(host='123.45.67.89:12345', external=True)
```

此时编排不会启动或停止该 Executor,而是假定它已被外部管理、并在 123.45.67.89:12345 持续可用。除生命周期外,外部 Executor 的行为与普通 Executor 完全一致——你甚至可以把同一个 Executor 同时添加到多个编排中。

源码层面对这一语义有清晰支撑:在 jina/orchestrate/deployments/init.py 中,Deployment 通过 external 属性(第 866-872 行)标记外部部署,并在启动流程中调用 _parse_external_replica_hosts_and_ports()(第 560 行)解析外部副本地址;同时 host / port 在外部模式下可传入列表,每个地址都会被视作 Executor 的一个副本(详见 Flow.add() 参数文档 jina/orchestrate/flow/base.py)。

为外部 Executor 启用 TLS

外部 Executor 同样支持通过 tls 加密连接:

```python
from jina import Deployment

Deployment(host='123.45.67.89:443', external=True, tls=True)
```
```python
from jina import Flow

Flow().add(host='123.45.67.89:443', external=True, tls=True)
```
使用 `tls` 连接外部 Executor,在接入由 JCloud 部署的外部 Executor 时尤其必要。

向外部 Executor 传递参数(认证等)

外部 Executor 可能需要额外的运行配置——典型的场景是需要认证才能访问的 Executor。此时可通过 grpc_metadata 参数传递认证信息:它是一个键值对字典,会附加到发送给该 Executor 的每一个 gRPC 请求上。

```python
from jina import Deployment

Deployment(
    host='123.45.67.89',
    port=443,
    external=True,
    grpc_metadata={'authorization': '<TOKEN>'},
)
```
```python
from jina import Flow

Flow().add(
    host='123.45.67.89',
    port=443,
    external=True,
    grpc_metadata={'authorization': '<TOKEN>'},
)
```
这里的 `grpc_metadata` 遵循 gRPC 中 `metadata` 的概念(即请求的键值对元数据,可携带认证令牌等信息)。在 <a href="https://link.gitcode.com/i/99a06ff15c65ccd852026a0835d7c7c7" target="_blank">jina/orchestrate/flow/base.py</a> 中,`Flow.add()` 的 `grpc_metadata` 参数说明为"The metadata to be passed to the gRPC request"(第 939 行),且在 Flow 构建 Gateway 时会将该元数据挂接到对应部署的连接配置上(第 699-701 行)。

七、小结

围绕"向编排添加 Executor",本文覆盖了三条主线:

  1. 选型(uses):内联类、py_modules 模块路径、YAML 配置、Hub 源码(jinaai://)、Hub 镜像(jinaai+docker://)、自定义镜像(docker://)六种形态,并明确了 JCloud 仅支持 YAML 与 Hub 镜像两种;对多 Executor 共享目录的场景使用 extra_search_paths 统一声明搜索路径。
  2. 配置覆盖:py_modules 注入依赖模块,uses_with 覆盖 __init__ 参数(未覆盖者回退默认值),uses_requests 重绑定端点路由(未被显式绑定的端点回落到 @requests 默认方法),uses_metas 改写 name / description 等内部元信息,workspace 指定工作目录。
  3. 共享与外部化:external=True + host + port 接入由其他编排托管的 Executor,tls=True 启用加密连接,grpc_metadata 携带认证元数据完成鉴权。

所有这些配置项都能在 jina/orchestrate/flow/base.py 的 Flow.add() 签名与 jina/orchestrate/deployments/init.py 的 Deployment 参数中找到源码级对应,并在 jina/serve/runtimes/worker/request_handling.py 的 _load_executor 中得到运行时注入,形成"API 声明 → 参数解析 → 运行时加载"的完整闭环。关于 Flow 与 Deployment 的更多编排参数,可继续阅读 docs/concepts/orchestration/flow.md、docs/concepts/orchestration/deployment.md 及 docs/concepts/orchestration/index.md。

登录后查看全文
jina