llm-coalesce가 여러 위젯의 LLM 요청을 하나로 합친다

브라우저 검증에서 서로 분리된 모듈 그래프 세 개는 각각 요청을 보냈다. 창 단위 레지스트리를 공유하자 요청은 하나로 줄었다.

오픈소스 TypeScript 라이브러리 llm-coalesce가 진행 중인 LLM 요청과 실시간 토큰 스트림을 동시에 호출한 여러 위젯이 공유하도록 한다. 각자 요청을 보내는 대신 하나의 응답 스트림을 함께 받아야 하는 앱 개발자에게 쓸모가 있다.

이게 뭔데

요청 합치기(request coalescing)는 동시에 들어온 같은 요청을 하나의 작업으로 처리하는 방식이다. 여러 사람이 함께 듣는 라디오를 떠올리면 쉽다. llm-coalesce는 AsyncIterable이나 ReadableStream을 받아 진행 중인 요청의 토큰 스트림을 여러 호출자에게 전달하며, 어떤 LLM SDK나 전송 방식을 쓸지는 이용자가 정한다.

저장소에는 라이브러리와 브라우저 데모가 들어 있다. 라이브 위젯 데모와 마이크로프런트엔드 데모는 API 키 없이 체험할 수 있다.

요청은 어떤 조건에서 합쳐지나

요청은 같은 레지스트리를 공유하고, 작업이 진행 중인 동안 요청 키가 정확히 일치할 때만 합쳐진다. 응답에 영향을 주는 입력은 모두 키에 포함해야 한다. 창 어댑터는 브라우저 탭 하나 안의 위젯을 조정한다. 탭 간 또는 분산 환경의 조정은 이 버전에 구현되지 않았다.

React를 비롯한 프레임워크에서 쓸 수 있다. React 앱은 선택 기능인 llm-coalesce/react의 useLlmStream 훅으로 텍스트·상태·오류를 받을 수 있고, 구독 정리는 자동으로 처리된다. 컴포넌트 간 요청을 조정하려면 안정적으로 유지되는 공유 코얼레서를 전달해야 한다. 핵심 진입점은 React를 가져오지 않는다. 자세한 내용은 라이브러리 사용 안내와 React 사용 안내를 참고하면 된다.

데모를 실행하려면

Node.js 18 이상과 npm이 필요하다. 저장소 루트에서 다음 명령을 실행한다.

cd llm-coalesce-demo
npm ci
npm start

로컬에서는 http://localhost:3000 또는 http://localhost:3000/microfrontends를 연다. 기본 제공자는 모의 텍스트를 스트리밍하므로 API 키가 필요 없다. 데모는 저장소에 포함된 vendor-packages/llm-coalesce-0.1.0.tgz 파일을 설치한다. 형제 디렉터리의 라이브러리를 빌드하거나 npm 레지스트리에서 내려받을 필요는 없다.

실제 Anthropic 제공자를 선택할 수도 있다. 설정은 데모 안내와 .env.example에 있다. 환경 변수는 셸이나 배포 플랫폼에서 설정해야 한다. 서버는 .env 파일을 자동으로 불러오지 않으며, API 키를 소스 관리에 넣지 않아야 한다.

라이브러리를 수정하고 검증하려면

저장소 루트에서 라이브러리를 개발하고 검사한다.

cd llm-coalesce
npm ci
npm run typecheck
npm test
npm run build

API는 라이브러리 문서에서 확인할 수 있고, 설계 세부 사항은 아키텍처 결정 문서에 정리돼 있다.

데모는 패키징된 스냅샷을 사용하므로 라이브러리 소스 코드를 수정해도 바로 반영되지 않는다. 수정 사항을 반영하려면 llm-coalesce/에서 빌드하고 패키지를 만든 뒤 데모에서 설치한다.

npm run build
npm pack --pack-destination ../llm-coalesce-demo/vendor-packages
cd ../llm-coalesce-demo
npm install ./vendor-packages/llm-coalesce-0.1.0.tgz

패키지 버전을 바꾸면 새 아카이브 파일명을 사용해야 한다. 갱신한 아카이브와 의존성 잠금 파일은 함께 커밋해야 한다.

데모를 검증하려면 llm-coalesce-demo/에서 다음 명령을 실행한다.

npm test
npx playwright install chromium
npm run test:browser

통합 테스트는 실제 서버를 대상으로 한다. 브라우저 검사는 서로 다른 모듈 그래프 세 개가 각자 격리된 레지스트리를 쓸 때 요청 세 개가 발생하고, 창 레지스트리를 공유할 때 요청 하나가 발생하는지 확인한다.

사용 전에 확인할 점

이 라이브러리는 MIT 라이선스를 따른다. 데모도 패키지 메타데이터에서 MIT를 선언한다. 라이선스를 확인할 수 있다.

이전 패키지 use-llm-stream은 제거됐지만 소스는 Git 기록에 남아 있다. 이전 튜토리얼은 과거 버전을 설명하므로 현재 API 안내와 구분해야 한다. 튜토리얼의 권장 연대순 목록은 데모 README에 있다. 원문은 라이브러리와 데모의 가격이나 지원 범위를 밝히지 않는다.