용도별 HTTP client를
서비스 수명 동안 공유한다

현재 전체 코드

import logging
from collections.abc import AsyncGenerator
from contextlib import asynccontextmanager

import httpx2
from fastapi import FastAPI

from app.api.router import api_router
from app.core.config import Settings, get_settings
from app.engines.turbofieldfare import TurboFieldfareAdapter


def create_app(settings: Settings | None = None) -> FastAPI:
    """Build a FastAPI application with explicit, testable dependencies."""
    resolved_settings = settings or get_settings()

    logging.basicConfig(
        level=resolved_settings.log_level,
        format="%(asctime)s %(levelname)s %(name)s %(message)s",
    )
    logger = logging.getLogger(resolved_settings.service_name)

    @asynccontextmanager
    async def lifespan(application: FastAPI) -> AsyncGenerator[None, None]:
        # Each client owns a pool; generation traffic cannot occupy probe slots.
        # Creating clients does not connect to the server or load a model.
        async with (
            httpx2.AsyncClient(
                base_url=str(resolved_settings.inference_base_url),
                timeout=httpx2.Timeout(
                    resolved_settings.inference_generation_timeout,
                    connect=resolved_settings.inference_connect_timeout,
                    pool=resolved_settings.inference_connect_timeout,
                ),
                limits=httpx2.Limits(max_connections=4, max_keepalive_connections=2),
                follow_redirects=False,
                trust_env=False,
            ) as generation_client,
            httpx2.AsyncClient(
                base_url=str(resolved_settings.inference_base_url),
                timeout=httpx2.Timeout(
                    resolved_settings.inference_probe_timeout,
                    connect=resolved_settings.inference_connect_timeout,
                    pool=resolved_settings.inference_connect_timeout,
                ),
                limits=httpx2.Limits(max_connections=2, max_keepalive_connections=2),
                follow_redirects=False,
                trust_env=False,
            ) as probe_client,
        ):
            application.state.inference_engine = TurboFieldfareAdapter(
                generation_client,
                probe_client=probe_client,
                model=resolved_settings.inference_model,
                probe_timeout=resolved_settings.inference_probe_timeout,
                generation_timeout=resolved_settings.inference_generation_timeout,
            )
            logger.info(
                "service_started version=%s environment=%s",
                resolved_settings.service_version,
                resolved_settings.environment,
            )
            try:
                yield
            finally:
                application.state.inference_engine = None
        logger.info("service_stopped")

    application = FastAPI(
        title="Local MoE Service API",
        version=resolved_settings.service_version,
        description="FastAPI gateway for local LLM inference.",
        lifespan=lifespan,
    )
    application.state.settings = resolved_settings
    application.include_router(api_router)
    return application


app = create_app()

import부터 차근차근 읽기

왜 client가 두 개인가?

이전에는 답변 생성과 상태 확인이 연결 4개짜리 풀 하나를 공유했다. 긴 생성 요청 4개가 응답을 기다리면 상태 확인도 빈 연결이 나기를 기다렸다. TurboFieldfare가 정상이어도 기본 3초의 연결 대기 제한을 넘겨 busy, 이어서 /readyz의 503으로 보일 수 있었다.

두 경로 모두 같은 TurboFieldfareServer로 향한다. 이제 생성 요청이 자기 연결 4개를 모두 사용해도 상태 확인용 연결은 차지하지 못한다. 하나의 풀을 6개로 늘리는 것과 다르다. 하나의 풀이라면 생성 요청 6개가 다시 모든 연결을 차지할 수 있기 때문이다.

AsyncClient 설정이 뜻하는 것

상태 확인 요청끼리는 여전히 최대 2개의 연결을 공유한다. 해당 풀이 포화되거나 실제 upstream이 응답하지 않으면 readiness는 실패할 수 있다. 이번 수정의 보장은 “생성 요청이 상태 확인용 풀을 점유하지 않는다”이지 “readiness가 무조건 성공한다”가 아니다.

Runtime 시간 순서

왜 try/finally가 필요한가?

yield 구간을 정상 종료하거나 이 구간으로 예외·취소가 전달되면 finally가 engine 참조를 제거한다. 이 설명은 Python이 정리 코드를 실행할 수 있는 종료 경로에 관한 것이다. 강제 프로세스 종료나 전원 차단까지 finally 실행을 보장하지는 않는다. 그 바깥의 async with는 두 HTTP client 각각의 aclose() 역할을 수행한다. 단, FastAPI는 자신이 시작하지 않은 TurboFieldfare process를 종료하지 않는다.

logging.basicConfig()는 process 전역 logging 설정이며 이미 handler가 구성된 경우 아무 효과가 없을 수 있다. Application factory가 logging까지 자동 격리한다는 뜻은 아니다. 현재 학습 단계에서는 단순한 형식을 사용하고, observability 단계에서 request ID와 구조화 log를 별도로 설계한다.