“프로세스가 산다”와
“추론할 준비가 됐다”를 나눈다

현재 전체 코드

from typing import Annotated

from fastapi import APIRouter, Depends, Request, Response, status

from app.api.dependencies import get_inference_engine
from app.engines.base import InferenceEngine, InferenceError
from app.schemas.system import HealthResponse, ReadinessResponse


router = APIRouter(tags=["system"])


@router.get(
    "/healthz",
    response_model=HealthResponse,
    status_code=status.HTTP_200_OK,
    summary="Check whether the FastAPI process is alive",
)
async def healthcheck(request: Request, response: Response) -> HealthResponse:
    """Return process liveness without checking external dependencies."""
    response.headers["Cache-Control"] = "no-store"
    settings = request.app.state.settings
    return HealthResponse(
        status="ok",
        service=settings.service_name,
        version=settings.service_version,
        environment=settings.environment,
    )


@router.get(
    "/readyz",
    response_model=ReadinessResponse,
    responses={503: {"model": ReadinessResponse}},
    summary="Check inference reachability and the configured model ID",
)
async def readiness(
    response: Response,
    engine: Annotated[InferenceEngine, Depends(get_inference_engine)],
) -> ReadinessResponse:
    response.headers["Cache-Control"] = "no-store"
    try:
        await engine.check_ready()
    except InferenceError as error:
        response.status_code = status.HTTP_503_SERVICE_UNAVAILABLE
        return ReadinessResponse(status="not_ready", error_code=error.code)
    return ReadinessResponse(status="ready")

Annotated[..., Depends(...)]를 풀어서 읽기

Client는 engine이라는 HTTP parameter를 보내지 않는다. FastAPI가 route 호출 전에 get_inference_engine(request)를 실행하고 반환 object를 인수로 넣는다. 이를 dependency injection이라고 한다.

/readyz 한 번의 내부 순서

오류 처리에 HTTPException을 쓰지 않고 Response status를 바꾼 뒤 동일한 ReadinessResponse를 반환했다. 성공과 실패가 같은 예측 가능한 JSON 모양을 유지해 monitor와 test가 간단해진다.

두 응답 계약

class ReadinessResponse(BaseModel):
    model_config = ConfigDict(frozen=True)

    status: Literal["ready", "not_ready"]
    dependency: Literal["inference"] = "inference"
    error_code: InferenceErrorCode | None = None

Cache-Control: no-store는 browser나 proxy가 과거의 ready 결과를 cache해 현재 상태처럼 보여주지 않게 한다.

Readiness가 보장하지 않는 것

• TurboFieldfare queue에 지금 빈자리가 있다는 보장은 아니다.
• 긴 prompt가 context limit 안에 들어간다는 보장은 아니다.
• 한 token이라도 실제로 생성했다는 보장은 아니다.
• 답변 내용이 정확하거나 빠르다는 품질 보장이 아니다.

Probe는 자주 호출되어야 하므로 model 생성을 포함하지 않는다. 실제 generation은 bounded smoke test와 이후 chat integration test에서 별도로 확인한다.