캐싱

개요

임베디드 계산이 포함된 문서를 렌더링하는 데 시간이 오래 걸릴 때는 실행 캐시를 추가하는 것을 고려할 수 있습니다. 캐시는 셀 실행 결과를 저장해 문서를 렌더링할 때마다 다시 실행하지 않도록 해줍니다.

Quarto는 Jupyter Cache와 Knitr Cache를 통합해 시간이 많이 걸리는 코드 청크를 캐시합니다. 두 캐시 기능은 서로 다른 특성을 가지며, 아래에서 각각 자세히 다룹니다.

Jupyter Cache

Jupyter Cache는 노트북의 모든 셀 출력을 캐시합니다. 노트북의 셀 중 하나라도 변경되면 모든 셀이 다시 실행됩니다.

Jupyter Cache를 사용하려면 먼저 jupyter-cache 패키지를 설치해야 합니다.

플랫폼	명령
Mac/Linux	Terminal `python3 -m pip install jupyter-cache`
Windows	Terminal `py -m pip install jupyter-cache`
Conda	Terminal `conda install jupyter-cache`

Julia 설치

Julia와 IJulia가 제공하는 통합 Python 환경을 함께 사용한다면, 대신 Julia용 Jupyter Cache 설치 안내를 따르세요.

문서에 캐시를 활성화하려면 cache 옵션을 추가합니다. 예:

---
title: "My Document"
format: html
execute: 
  cache: true
jupyter: python3
---

프로젝트 수준에서도 캐싱을 지정할 수 있습니다. 예:

project:
  type: website
  
format:
  html:
    theme: united
    
execute:
  cache: true

코드 셀 밖의 변경(예: 마크다운 서술)은 문서 캐시를 무효화하지 않습니다. 그래서 글쓰기 부분만 작업할 때 캐싱은 매우 편리합니다.

Jupyter Cache에는 노트북 캐시를 분석하고 관리할 수 있는 jcache 명령줄 유틸리티가 포함되어 있습니다. 자세한 내용은 Jupyter Cache 문서를 참고하세요.

Knitr Cache

Knitr Cache는 문서 전체가 아니라 개별 셀 수준에서 동작합니다. 이는 편리할 수 있지만, 셀 간 의존성 관리에 대한 특별한 요구 사항이 생깁니다.

표준 YAML 옵션으로 문서 또는 프로젝트 수준에서 Knitr 캐시를 활성화할 수 있습니다.

---
title: "My Document"
format: html
execute: 
  cache: true
---

셀별로 캐싱을 활성화할 수도 있습니다(이 경우 문서 수준 옵션은 설정하지 않습니다).

```{r}
#| cache: true

summary(cars)
```

Knitr 캐싱 동작에 영향을 주는 다양한 셀 수준 옵션이 있습니다. 자세한 내용은 Knitr 셀 옵션 문서를 참고하세요. 또한 Yihui Xie의 캐시 무효화 글도 좋은 참고 자료입니다.

렌더링

문서 코드를 변경하지 않고도 quarto render 명령줄 옵션으로 캐싱 동작을 제어할 수 있습니다. 모든 청크에 캐시를 강제로 사용하거나, 옵션에 지정되어 있더라도 캐시를 비활성화하거나, 캐시가 무효화되지 않았더라도 강제로 새로고침할 수 있습니다.

Terminal

# 캐시 사용(문서 옵션에 활성화되어 있지 않아도)
quarto render example.qmd --cache 

# 캐시 사용 안 함(문서 옵션에 활성화되어 있어도)
quarto render example.qmd --no-cache 

# 캐시 사용 + 강제 새로고침(셀 변경이 없어도)
quarto render example.qmd --cache-refresh

대안

렌더링 시간이 길어 캐싱을 고려한다면, 캐싱 외에도 아래 대안을 함께 고려할 수 있습니다.

실행 비활성화

서술/마크다운 작업만 하고 있다면 실행을 완전히 비활성화하는 것이 좋습니다. enabled: false 실행 옵션으로 설정합니다. 예:

---
title: "My Document"
format: html
execute: 
  enabled: false
---

Jupyter .ipynb 노트북으로 작성하는 경우(일반 텍스트 .qmd가 아닌), 이는 이미 기본 동작입니다. 즉, quarto render를 호출해도 실행은 되지 않고, 노트북에서 작업할 때 실행이 이루어집니다.

실행 고정

프로젝트에서 여러 문서를 한꺼번에 렌더링할 때 누적 비용이 걱정된다면 freeze 옵션을 고려하세요.

freeze 옵션을 사용하면 전체 프로젝트 렌더링 중 계산 문서를 다시 렌더링하지 않도록 하거나, 소스 파일이 변경될 때만 다시 렌더링하도록 지정할 수 있습니다.

execute:
  freeze: true  # 프로젝트 렌더링 중 다시 렌더링하지 않음

execute:
  freeze: auto  # 소스가 변경될 때만 다시 렌더링

freeze는 전체 프로젝트 렌더링 중 실행 여부를 제어합니다. 단일 문서나 프로젝트 하위 디렉터리를 증분 렌더링하면 코드는 항상 실행됩니다. 예:

Terminal

# 단일 문서 렌더링(항상 코드 실행)
quarto render document.qmd

# 프로젝트 하위 디렉터리 렌더링(항상 코드 실행)
quarto render articles

프로젝트에서 freeze를 사용하는 방법은 프로젝트 실행 관리 문서를 참고하세요.