Jina 编排实战:如何用 `uses` 定义与配置 Executor(本地与外部 Executor 全指南)
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",本文覆盖了三条主线:
- 选型(
uses):内联类、py_modules模块路径、YAML 配置、Hub 源码(jinaai://)、Hub 镜像(jinaai+docker://)、自定义镜像(docker://)六种形态,并明确了 JCloud 仅支持 YAML 与 Hub 镜像两种;对多 Executor 共享目录的场景使用extra_search_paths统一声明搜索路径。 - 配置覆盖:
py_modules注入依赖模块,uses_with覆盖__init__参数(未覆盖者回退默认值),uses_requests重绑定端点路由(未被显式绑定的端点回落到@requests默认方法),uses_metas改写name/description等内部元信息,workspace指定工作目录。 - 共享与外部化:
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。