Tesseract-Torch: 컨테이너화한 과학 계산 코드를 PyTorch 자동미분에 연결하는 라이브러리

9bow · 7월 10, 2026, 2:30오전

Tesseract-Torch 소개

실제 과학 연구 파이프라인은 하나의 언어나 프레임워크로 끝나지 않는 경우가 많습니다. 메시 생성기는 C++로, 솔버는 Julia로, 후처리는 Python으로 작성돼 있는 식입니다. 이런 이기종 도구를 하나로 묶어 함께 동작시키는 것도 번거롭지만, 그 파이프라인 전체에 걸쳐 그래디언트를 흘려보내 최적화까지 하는 일은 훨씬 더 어렵습니다. 이 문제를 풀기 위해 Pasteur Labs는 Tesseract Core를 만들었습니다. 어떤 언어로 작성된 과학 계산 코드든 Docker 컨테이너로 감싸 CLI·REST API·Python SDK라는 동일한 인터페이스로 실행할 수 있게 하고, 컴포넌트마다 야코비안(Jacobian)·벡터-야코비안 곱(VJP)·야코비안-벡터 곱(JVP) 같은 미분 값을 노출해 이기종 파이프라인 전체를 미분 가능하게 이어붙일 수 있도록 설계된 프레임워크입니다.

Tesseract-Torch는 이 Tesseract Core를 PyTorch 생태계에 연결하는 가벼운 확장입니다. apply_tesseract(tesseract, inputs)라는 단 하나의 함수로 어떤 Tesseract든 PyTorch의 자동 미분 그래프 안에 끼워 넣을 수 있으며, 역전파(reverse-mode)와 정전파(forward-mode) 자동 미분을 모두 지원합니다. 즉 Julia나 C++, Fortran으로 짠 시뮬레이터를 Tesseract로 패키징해두면, PyTorch 학습 루프 안에서 다른 nn.Module과 똑같이 .backward()를 호출해 그래디언트를 얻을 수 있습니다.

Tesseract-Torch 자체는 API 표면이 매우 작습니다. 텐서를 넘파이(NumPy) 배열로 변환해 Tesseract에 전달하고, Tesseract의 스키마를 읽어 어떤 입출력이 미분 대상인지 판단한 뒤, 결과를 다시 grad_fn이 연결된 torch.Tensor로 되돌리는 역할만 합니다. Pasteur Labs는 같은 방식으로 JAX용 확장인 Tesseract-JAX와, Tesseract를 웹 앱으로 자동 변환해주는 Tesseract-Streamlit도 함께 공개하고 있습니다. Tesseract-Torch는 2026년 6월 23일 v0.1.0으로 첫 정식 릴리즈를 냈습니다.

Tesseract-Torch의 동작 원리

apply_tesseract 하나로 끝나는 API

Tesseract-Torch의 API는 apply_tesseract(tesseract, inputs) 함수 하나뿐입니다. tesseract 인자로 실행 중인 Tesseract 인스턴스를, inputs 인자로 그 Tesseract의 입력 스키마와 맞는 중첩 dict를 넘기면, 그래디언트가 필요한 배열 필드에는 torch.Tensor를, 그 외에는 일반 Python·NumPy 값을 그대로 채워 넣을 수 있습니다.

import torch
from tesseract_core import Tesseract
from tesseract_torch import apply_tesseract

# Tesseract 로드
t = Tesseract.from_image("vectoradd_torch")
t.serve()

# PyTorch 텐서로 실행
x = torch.ones(1000, requires_grad=True)
y = torch.ones(1000)

def vector_sum(x, y):
    res = apply_tesseract(t, {"a": {"v": x}, "b": {"v": y}})
    return res["vector_add"]["result"].sum()

loss = vector_sum(x, y)
loss.backward()
print(x.grad)  # Tesseract의 VJP 엔드포인트를 거쳐 온 그래디언트

# 정전파(forward-mode) 자동 미분도 지원합니다
import torch.autograd.forward_ad as fwAD

with fwAD.dual_level():
    x_dual = fwAD.make_dual(x.detach(), torch.ones_like(x))
    result = apply_tesseract(t, {"a": {"v": x_dual}, "b": {"v": y}})
    _, tangent = fwAD.unpack_dual(result["vector_add"]["result"])

어떤 필드가 미분 대상인지는 스키마가 정한다

Tesseract는 Pydantic BaseModel로 입출력 스키마(InputSchema, OutputSchema)를 정의하며, 이때 Differentiable[...]로 감싼 필드만 자동 미분에 참여합니다. 감싸지 않은 필드는 값이 매 호출마다 바뀌더라도 PyTorch의 autograd 입장에서는 상수로 취급됩니다.

from pydantic import BaseModel
from tesseract_core.runtime import Array, Differentiable, Float32

class InputSchema(BaseModel):
    x: Differentiable[Array[(3,), Float32]]   # 미분 대상
    label: Array[(1,), Float32]               # 미분 대상 아님

class OutputSchema(BaseModel):
    loss: Differentiable[Array[(), Float32]]  # 미분 대상
    metadata: Array[(4,), Float32]            # 미분 대상 아님

apply_tesseract는 이 스키마를 읽어 어떤 출력을 grad_fn이 붙은 torch.Tensor로 반환할지, 어떤 출력을 있는 그대로의 NumPy 배열·스칼라로 반환할지 결정합니다. 미분 대상이 아닌 출력을 PyTorch 후속 연산에 쓰려면 torch.as_tensor()로 직접 변환해야 합니다.

알아두어야 할 제약(Sharp edges)

Tesseract-Torch를 쓸 때 걸려 넘어지기 쉬운 지점이 README와 문서에 명시돼 있습니다. 역전파(.backward(), torch.autograd.grad)를 쓰려면 해당 Tesseract가 vector_jacobian_product 엔드포인트를, 정전파(torch.autograd.forward_ad)를 쓰려면 jacobian_vector_product 엔드포인트를 구현하고 있어야 합니다. 이 엔드포인트가 없는 상태로 해당 자동 미분 모드를 쓰면 NotImplementedError가 발생하며, apply_tesseract 자체(순전파)는 이 엔드포인트 유무와 무관하게 항상 동작합니다. 또한 apply_tesseract는 .backward(), torch.autograd.grad, torch.autograd.forward_ad 같은 PyTorch 표준 autograd API와는 함께 쓸 수 있지만, torch.func.vjp·torch.func.jvp·torch.func.grad·torch.func.vmap 같은 torch.func 변환 안에서는 사용할 수 없습니다. 이 변환들이 만들어내는 함수화된(functionalized) 텐서는 NumPy 배열로 변환할 수 없어, Tesseract 엔드포인트가 요구하는 형식과 맞지 않기 때문입니다. torch.func 변환 내부에서 apply_tesseract를 호출하면 명확한 에러가 발생합니다.

Tesseract-Torch 설치 및 사용법

Tesseract-Torch를 쓰려면 Docker와 Python 3.10 이상이 필요합니다.

# 1. Tesseract-Torch 설치
$ pip install tesseract-torch

# 2. 예시 Tesseract 빌드
$ git clone https://github.com/pasteurlabs/tesseract-torch
$ tesseract build tesseract-torch/examples/simple/vectoradd_torch

빌드가 끝나면 위 "동작 원리" 절의 코드처럼 Tesseract.from_image()로 이미지를 불러와 apply_tesseract로 PyTorch 프로그램에 끼워 넣으면 됩니다. 저장소의 examples/simple 디렉터리에는 이 벡터 덧셈 예시를 노트북으로 단계별로 따라갈 수 있는 demo.ipynb도 함께 들어 있습니다. Tesseract 자체를 빌드하는 방법 등 더 자세한 설치 과정은 Tesseract Core 문서의 설치 안내를 참고하면 됩니다.

Tesseract-Torch의 라이선스

Tesseract-Torch는 Apache License 2.0로 공개되어 있어 개인 및 상업적 목적으로 자유롭게 사용할 수 있습니다. 다만 Tesseract는 Pasteur Labs, Inc.의 등록 상표이므로, 상표 사용에는 별도 허가가 필요합니다.

Tesseract-Torch 문서 사이트

Tesseract-Torch 프로젝트 GitHub 저장소

이 글은 GPT 모델로 정리한 글을 바탕으로 한 것으로, 원문의 내용 또는 의도와 다르게 정리된 내용이 있을 수 있습니다. 관심있는 내용이시라면 원문도 함께 참고해주세요! 읽으시면서 어색하거나 잘못된 내용을 발견하시면 덧글로 알려주시기를 부탁드립니다.

파이토치 한국 사용자 모임이 정리한 이 글이 유용하셨나요? 회원으로 가입하시면 주요 글들을 이메일로 보내드립니다! 텔레그램(Telegram)이나 Slack/Discord/Teams/Dooray/GoogleChat 등으로도 새 글 알림을 받으실 수 있습니다.

아래쪽에 좋아요를 눌러주시면 새로운 소식들을 정리하고 공유하는데 힘이 됩니다~