docs(lmcache): MP 모드 설정과 K8s 배포 형태 보강

[juwon8891]

배경

lmcache.md는 LMCache의 개념과 추론 인프라 내 위치를 잘 설명하고 있으나, 실제 설정 예시가 없어 형제 문서인 kv-cache-optimization.md(vllm serve 플래그 블록 포함)와 깊이가 불균형합니다. 또한 L3 계층을 "원격 스토리지"로만 서술해 실제로 어떤 백엔드를 어떤 기준으로 고르는지가 빠져 있습니다.

변경 사항

vLLM 연동 설정 섹션 신설 — LMCache 공식 문서가 권장하는 MP(multiprocess) 모드 기준

• lmcache server 기동 명령과 LMCacheMPConnector 접속 설정
• 주요 서버 플래그 표 (--l1-size-gb, --eviction-policy, --chunk-size, --hash-algorithm 등)
• vLLM 0.20.0을 기준으로 kv_connector_module_path 지정 필요 여부가 갈리는 점을 :::warning으로 명시
• --hash-algorithm builtin을 쓸 때만 PYTHONHASHSEED 통일이 필요하다는 조건을 :::tip으로 분리

저장 백엔드 선택 섹션 신설

• --l2-adapter JSON 방식과 지원 어댑터 type 분류표
• 선택 기준으로 공유 범위(노드 로컬 vs 클러스터)를 제시 — 스케일아웃 후 캐시 재사용 가능 여부가 실제 판단 근거가 되는 점
• LMCache MP의 L1·L2가 문서 상단 그림의 L1(GPU HBM)·L2(CPU DRAM) 표기와 다른 축임을 :::info로 구분

K8s 배포 형태 섹션 신설

• 공식 배포 가이드의 DaemonSet + Deployment 패턴 (sidecar 아님), status.hostIP 기반 디스커버리
• --supported-transfer-mode(auto/lmcache_driven/engine_driven)별 요구사항 차이. /dev/shm 마운트는 무조건 요구가 아니라 전송 경로에 딸린 조건이며, --shm-name이 빈 문자열이면 pickle 기반 전송을 사용해 /dev/shm 없이도 동작한다는 점을 명시
• hostNetwork: true와 /dev/shm hostPath가 Pod Security Standards의 baseline·restricted에서 금지되는 항목이라 요구 권한이 성능과 무관하게 채택 가능 여부를 결정할 수 있다는 점, 그리고 정책이 엄격한 환경에서는 engine_driven + pickle 전송으로 그 의존을 제거해볼 수 있다는 점을 :::warning으로 함께 제시

참고 자료 보강 — MP 모드 개요, 설정 레퍼런스, 배포 가이드

모드 선택에 대해

in-process 모드가 아니라 MP 모드 기준으로 작성했습니다. 공식 문서가 in-process 페이지에 "documents the behavior of LMCache's in-process mode (deprecated)" 로 명시하고 있어, 문서가 legacy 경로를 가르치지 않는 편이 낫다고 판단했습니다.

검증

• 모든 플래그·어댑터 type·연결 설정은 MP Configuration Reference와 MP Deployment Guide 기준으로 대조 (2026-08 확인). 표의 기본값은 문서상 default 값이며 예시값과 구분했습니다
• 추가한 bash 블록 3개 모두 bash -n 통과 — 복사·붙여넣기 가능
• 내부 상대 링크 전수 해석 확인
• npm run validate-metadata — 이 파일 에러 없음
• markdownlint 결과가 변경 전과 동일 (기존 6건, 신규 0건). 기존 6건은 참고 자료 섹션의 MD022/MD032로 이 PR 범위 밖이라 손대지 않았습니다
• 백엔드별 필수 파라미터는 어댑터마다 달라 단정하지 않고 공식 레퍼런스로 연결했습니다

확인 부탁드립니다

• last_update.author를 기여자 명의로 변경했습니다. 날짜만 갱신하고 원저자 이름을 두면 렌더링된 페이지가 사실과 달라지기 때문인데, 레포 관행과 다르면 되돌리겠습니다.
• security-governance/index.md로 거는 ../../../ 크로스섹션 상대 링크는 레포에 선례가 없습니다(기존은 섹션 내 ../../까지). 파일 해석·빌드는 정상이나, 관행과 다르면 조정하겠습니다.

---

작성에 Claude Code를 활용했습니다. 모든 플래그와 설정 키는 위에 링크한 공식 문서를 직접 대조해 검증했습니다.

[juwon8891]

@devfloor9 Can you review this one?

[devfloor9]

기여 감사합니다. 추가된 플래그·커넥터 설정·전송 모드 서술을 공식 문서(docs.lmcache.ai mp/*, getting_started/quickstart)와 전수 대조했고, 대부분 정확함을 확인했습니다. 깊이·admonition 사용도 model-serving 하위 문서 관행에 부합합니다. 머지 전 수정이 필요한 항목 3건과 소소한 코멘트가 있습니다.

머지 전 수정 요청 (3건)

1. 삭제된 경로로의 링크

PR 작성(8/23) 이후 main에서 docs/security-governance/ 카테고리가 docs/eks-best-practices/security-authn/(라벨 "보안 & 거버넌스")으로 통합되면서 디렉터리가 삭제됐습니다. :::warning 내 링크를 아래로 변경 부탁드립니다. 참조하시려는 워크로드 보안 절은 새 index에 그대로 있습니다.

-프로파일별 제약 내용은 [보안 & 거버넌스](../../../security-governance/index.md)의 워크로드 보안 절을 참조하세요.
+프로파일별 제약 내용은 [보안 & 거버넌스](../../../eks-best-practices/security-authn/index.md)의 워크로드 보안 절을 참조하세요.

레포가 onBrokenMarkdownLinks: 'warn' 설정이라 빌드는 통과하지만 dead link로 배포되는 상태입니다. 크로스섹션 상대 링크 자체는 문제없습니다 — 열어주신 질문에 대한 답: 이 형태(../../../<카테고리>/...)로 진행해 주세요.

2. --supported-transfer-mode 기본값

표에 auto (기본)으로 표기되어 있으나, MP Configuration Reference 기준 기본값은 lmcache_driven입니다. 표의 "(기본)" 표기를 lmcache_driven 행으로 옮겨 주세요.

3. Prometheus 메트릭 포트

"HTTP 포트(기본 8080)는 Prometheus 호환 메트릭과 관리 API를 노출합니다"에서, 8080(--http-port)은 관리·헬스체크용 FastAPI 프런트엔드이고 Prometheus 메트릭은 별도 --prometheus-port(기본 9090)로 노출됩니다. 두 포트를 분리해 서술 부탁드립니다.

author 표기

원저자 표기는 유지하되 기여자를 병기하는 형태로 부탁드립니다. 지적해 주신 "렌더링 페이지가 사실과 달라지는" 문제와 문서 오너십 표기를 함께 해결하는 방식으로, 이 레포의 외부 기여 표기 관행으로 삼으려 합니다.

last_update:
  date: "2026-08-23"
  author: YoungJoon Jeong · Juwon Hwang

논블로킹 코멘트

• 헤딩 명사구화: ### 전송 경로에 따라 요구사항이 달라집니다 → ### 전송 경로별 요구사항 (레포 스타일 가이드: 문장형 헤딩 지양)
• 어댑터 표: 공식 레퍼런스에는 nixl_store_dynamic도 등록되어 있습니다. "지원하는 어댑터 type" 단정 대신 "주요 어댑터 type"으로 완화하거나 항목을 추가해 주세요.
• 버전 확인 시점: LMCache는 MP 모드 최소 버전을 문서에 명시하지 않으므로("latest dev branch" 권장만) "2026-08 공식 문서 기준" 같은 확인 시점을 본문에 남겨 주시면 좋겠습니다.
• 참고로 PR 설명에 인용하신 "(deprecated)"는 공식 문서에서는 "legacy"로만 표기됩니다 — 본문 서술("legacy로 분류")은 정확하니 그대로 두시면 됩니다.

i18n

i18n/en/.../lmcache.md 동기화는 요구하지 않습니다. 머지 후 메인테이너가 처리할 예정입니다.

[juwon8891]

402d96d로 반영했습니다.

머지 전 수정 3건

1. 링크 → ../../../eks-best-practices/security-authn/index.md. 파일 내 상대 링크 12개 전수 재확인했습니다.
2. --supported-transfer-mode — 레퍼런스 원문이 lmcache_driven (default)가 맞습니다. 제가 값 나열 순서를 기본값으로 잘못 읽었습니다. "(기본)" 표기를 옮겼습니다.
3. 8080(--http-port, 관리·헬스체크)과 9090(--prometheus-port, /metrics)을 분리 서술했습니다.

author — YoungJoon Jeong · Juwon Hwang. 레포에 병기 선례가 없어 이 커밋이 첫 사례입니다. 관행으로 삼으신다면 구분자를 스타일 가이드에 고정해 두시는 편이 좋겠습니다.

논블로킹 — 헤딩 명사구화, 확인 시점(2026-08) 본문 명시, "(deprecated)"는 지적하신 대로 제 PR 설명 쪽 오류였습니다(본문 유지). 어댑터 표는 nixl_store_dynamic 추가와 "주요"로 완화를 함께 했습니다 — 동적 연결되는 p2p도 있어 항목을 더해도 전수 나열은 아니라서요.

검증 — 상대 링크 전수 해석, bash 블록 3개 bash -n 통과. 작업 환경에 node가 없어 validate-metadata·markdownlint는 재실행하지 못했습니다. 변경된 프런트매터가 author 한 줄뿐이라 영향은 없어 보이지만 CI로 확인 부탁드립니다.