본문으로 건너뛰기

synapse_sdk.plugins.actions.inference.deployment

Ray Serve 배포 액션 기반 클래스.

DeploymentProgressCategories​

class DeploymentProgressCategories:
    INITIALIZE = 'initialize'
    DEPLOY = 'deploy'
    REGISTER = 'register'

BaseDeploymentAction​

class BaseDeploymentAction(BaseAction[P]):

BaseServeDeployment 서브클래스를 Ray Serve 에 배포하기 위한 기반 클래스입니다. Ray 초기화, 데코레이터를 적용한 serve 배포, 백엔드 등록을 처리합니다.

클래스 속성​

속성타입설명
progressDeploymentProgressCategories진행률 카테고리 상수
entrypointtype | None배포할 BaseServeDeployment 서브클래스

프로퍼티​

client​

@property
def client(self) -> BackendClient

런타임 컨텍스트의 백엔드 클라이언트.

agent_client​

@property
def agent_client(self) -> AgentClient

Serve 애플리케이션 등록을 위한 agent 클라이언트.

메서드​

ray_init​

def ray_init(self, **kwargs: Any) -> None

Ray 클러스터 연결을 초기화합니다. 환경에 지정된 클러스터에 연결합니다.

deploy​

def deploy(self) -> None

entrypoint 클래스를 Ray Serve 에 배포합니다. @serve.deployment 와 @serve.ingress(app) 데코레이터를 자동으로 적용하며, 리소스 구성에는 get_ray_actor_options() 를, URL 라우팅에는 get_route_prefix() 를 사용합니다.

serve.run(...) 호출 직전에 _check_serve_capacity(ray_actor_options, serve_options) 를 실행합니다. agent 가 용량을 거부하거나 도달 불가능할 때 RuntimeError 를 발생시킵니다 (아래 참조).

_check_serve_capacity (SYN-7005)​

def _check_serve_capacity(
    self,
    ray_actor_options: dict[str, Any],
    serve_options: dict[str, Any],
) -> None

사전(pre-flight) 클러스터 용량 게이트. serve.run(...) 직전에 ctx.agent_client.check_feasibility(kind='serve', ...) 를 단 한 번 호출합니다. 사용자 노출 분기 / 페이로드 매트릭스는 Inference Actions — Capacity Gate 를 참고하세요.

발생 예외:

  • agent 가 allowed=False 를 반환할 때 RuntimeError('Serve deploy denied: insufficient cluster capacity ([reasons])').
  • ClientError / ClientTimeoutError / TimeoutError / ConnectionError / OSError / 형식 오류 응답 시 RuntimeError('Serve deploy capacity check failed: agent unreachable ({error_type})'). 원본 예외는 __cause__ 로 attach.

우아한 스킵: ctx.agent_client is None 일 때 WARNING: serve capacity gate skipped: agent_client not provided 를 출력하고 반환합니다.

모듈 레벨 상수(_CAPACITY_DENIED_MSG, _CAPACITY_UNREACHABLE_MSG, _CAPACITY_SKIP_LOG)는 다운스트림 테스트의 monkey-patching 용으로 export 됩니다.

register_serve_application​

def register_serve_application(self) -> int | None

배포된 serve 애플리케이션을 Synapse 백엔드에 등록합니다.

반환값: 생성된 경우 serve 애플리케이션 ID, 그렇지 않으면 None.

구성 메서드​

배포 동작을 커스터마이징하려면 다음을 오버라이드합니다.

get_serve_app_name​

def get_serve_app_name(self) -> str

기본값: SYNAPSE_PLUGIN_RELEASE_CODE 환경 변수.

get_route_prefix​

def get_route_prefix(self) -> str

기본값: /{SYNAPSE_PLUGIN_RELEASE_CHECKSUM} 또는 /{md5(app_name)}.

get_ray_actor_options​

def get_ray_actor_options(self) -> dict[str, Any]

기본값: 액션 params 에서 num_cpus, num_gpus, memory 를 추출합니다.

get_runtime_env​

def get_runtime_env(self) -> dict[str, Any]

기본값: 빈 dict {}.

사용 예​

완성된 예제는 Inference Actions 를 참고하세요.