콘텐츠로 이동

마이그레이션 가이드: DESILO FHE 1.x에서 2.0으로

DESILO FHE 2.0에는 API, 지원되는 설정 및 직렬화 형식에서 호환성을 깨는 여러 변경 사항이 포함되어 있습니다.

이 가이드는 기존 프로그램을 DESILO FHE 1.x에서 2.0으로 이전하는 데 필요한 변경 사항을 설명합니다. 신규 기능과 성능 개선 사항에 대한 전체 내용은 릴리스 노트를 참고하시기 바랍니다.

1. 엔진 생성 방식 변경

Engine 생성자의 모든 인자는 이제 키워드 인자로만 전달할 수 있습니다. 또한 두 인자의 이름이 변경되었습니다.

1.x 2.0
use_bootstrap bootstrap
use_multiparty multiparty

변경 전:

from desilofhe import Engine

engine = Engine("gpu", use_bootstrap=True)

변경 후:

from desilofhe import Engine

engine = Engine(mode="gpu", bootstrap=True)

다자간 연산 설정에도 동일한 변경 사항이 적용됩니다.

engine = Engine(mode="gpu", multiparty=True)

인자 없이 엔진을 생성하는 것은 여전히 가능합니다.

engine = Engine()

기본 설정은 최대 곱셈 레벨이 7인 CKKS 엔진입니다.

2. 회전 및 순환 연산 변경

DESILO FHE 2.0에서는 roll과 rotate의 이동 방향을 구분합니다.

  • roll은 각 요소를 오른쪽으로 이동시킵니다.
  • rotate는 각 요소를 왼쪽으로 이동시킵니다.

이전 버전의 rotate는 현재 roll에 해당하는 방향으로 이동시켰습니다. 기존 코드의 동작을 유지하려면 rotate를 roll로 변경해야 합니다. 또한 모든 순환 관련 함수에서 이동량을 나타내는 인자 이름이 delta에서 shift로 변경되었습니다.

변경 전:

rotated = engine.rotate(ciphertext, rotation_key, delta=1)

변경 후:

rolled = engine.roll(ciphertext, roll_key, shift=1)

관련 함수, 키 및 인자의 변경 사항은 다음과 같습니다.

1.x 2.0
rotate roll
rotate_many roll_many
create_rotation_key create_roll_key
create_fixed_rotation_key create_fixed_roll_key
delta shift
회전 키 순환 키
고정 회전 키 고정 순환 키

delta에서 shift로의 변경은 키 생성과 여러 이동량을 받는 연산을 포함하여 모든 순환 관련 함수에 적용됩니다. 1.15 버전에서 도입된 roll을 이미 사용하고 있다면 이동 방향을 변경할 필요는 없습니다.

순환 키 생성

새로운 순환 키 생성 함수를 사용합니다.

secret_key = engine.create_secret_key()

roll_key = engine.create_roll_key(secret_key)
fixed_roll_key = engine.create_fixed_roll_key(secret_key, shift=1)

고정 순환 키는 CKKS와 GL 모두에서 사용할 수 있습니다.

GL에서는 고정 순환 키를 생성할 때 축을 지정해야 합니다.

fixed_roll_key = engine.create_fixed_roll_key(secret_key, shift=1, axis=0)

CKKS에서는 axis 속성의 값이 None입니다.

level 인자는 이제 반드시 키워드 인자로 전달해야 합니다.

fixed_roll_key = engine.create_fixed_roll_key(secret_key, shift=1, level=2)

이는 shift, axis, level이라는 세 정수 인자 사이의 혼동을 방지하기 위한 변경입니다.

부트스트랩 키 재사용

이제 부트스트랩 키를 roll, roll_many, rotate 연산에 직접 사용할 수 있습니다. 이미 부트스트랩을 사용하는 프로그램이라면 별도의 순환 키를 생략하여 메모리 사용량을 줄일 수 있습니다.

3. 연산 키 변경

DESILO FHE 2.0에는 키가 필요한 대부분의 연산에 사용할 수 있는 연산 키(Evaluation Key)가 도입되었습니다. 이전 버전에서는 일부 연산, 특히 부트스트랩을 수행할 때 여러 개의 키를 별도로 전달해야 했습니다.

연산 키는 평가에 필요한 키들을 하나로 통합하여 키 관리를 간소화합니다. 암호화와 복호화에는 여전히 각각의 키가 사용됩니다. 기존 코드를 이전할 때 여러 연산 키를 개별적으로 전달하는 대신 통합 연산 키를 사용하는 것을 고려해보실 수 있습니다.

4. GL 곱셈 변경

GL의 아다마르 곱셈 API가 CKKS와 일관성을 갖도록 변경되었습니다.

1.x 2.0
hadamard_multiply multiply
아다마르 곱셈 키 재선형화 키

변경 전:

result = engine.hadamard_multiply(
    ciphertext1, ciphertext2, hadamard_multiplication_key
)

변경 후:

result = engine.multiply(ciphertext1, ciphertext2, relinearization_key)

이제 GL에서는 재선형화 없이도 곱셈을 수행할 수 있습니다. 이 경우 결과 암호문은 일반적인 2개 대신 3개의 다항식을 포함하며, 재선형화하지 않고 직접 복호화할 수 있습니다.

이를 통해 재선형화된 암호문이 필요하지 않은 경우 불필요한 연산 비용을 절약할 수 있습니다. 현재 2.0.0에서 3개의 다항식을 가진 암호문에 지원되는 연산은 복호화뿐이지만 점차 추가될 예정입니다.

5. 부트스트랩 설정 변경

DESILO FHE 2.0에서는 17레벨 부트스트랩만 지원합니다.

다음 설정과 기능들은 더 이상 지원되지 않습니다.

1.x 2.0
다른 일반 부트스트랩 방식 17레벨 부트스트랩 사용
손실 부트스트랩 일반 부트스트랩 사용
부호 부트스트랩 직접적인 대체 기능 없음
대형 부트스트랩 키 지원되는 부트스트랩 키 사용
사용자 지정 부트스트랩 스테이지 수 기본 설정 사용

mod_raise 함수와 사용자 지정 비밀값을 사용하는 비밀 키는 더 이상 사용을 권장하지 않습니다. 이 기능들은 사용자 지정 부트스트랩을 위해 도입되었지만, 17레벨 부트스트랩의 모듈러스 구성에서는 더 이상 사용자 지정 부트스트랩을 지원할 수 없습니다.

사용자 지정 부트스트랩을 사용하는 프로그램은 지원되는 부트스트랩 설정을 사용하도록 연산 과정을 재설계해야 합니다.

6. CKKS 파라미터 변경

CKKS에서 슬롯 수 32768은 더 이상 지원되지 않습니다. 이 설정은 키의 크기가 과도하게 크고 저레벨에서 인코딩 및 디코딩 오차가 컸습니다.

32768 슬롯을 사용하는 프로그램은 다른 CKKS 설정으로 변경해야 합니다. 가장 큰 CKKS 엔진이 제공하는 36개의 곱셈 레벨보다 많은 레벨이 필요한 경우에는 부트스트랩 엔진을 사용하시기 바랍니다.

다항식 계수 개수의 로그값을 직접 지정하는 기능도 더 이상 지원되지 않습니다. 대신 미리 정의된 엔진 설정을 사용해야 합니다.

7. GL 형상 변경

가장 안쪽 차원의 크기가 256 이상인 GL 형상은 더 이상 지원되지 않습니다. 이러한 형상을 사용하는 프로그램은 다른 지원되는 형상으로 변경해야 합니다.

DESILO FHE 2.0에는 새로운 배치 크기 162와 486도 추가되어 GL 형상을 선택할 때 더 다양한 구성을 사용할 수 있습니다. 지원되는 GL 형상과 최대 레벨의 전체 목록은 지원되는 형상을 참고하시기 바랍니다.

8. 행렬 곱셈 및 희소 (Sparse) 인코딩 이전

CKKS 행렬 곱셈과 희소 인코딩은 더 이상 지원되지 않습니다. 이러한 기능을 사용하는 프로그램은 연산 과정을 변경해야 합니다.

연산의 특성에 따라 다음과 같은 대안을 고려할 수 있습니다.

  • 효율적인 패킹 기법과 암호문 회전 및 곱셈을 사용하여 CKKS 행렬 곱셈을 직접 구현합니다.
  • GL로 이전합니다.

다만 소규모 프로그램에서는 GL에 필요한 형상이 지나치게 클 수 있습니다. 향후 CKKS 행렬 곱셈을 위한 추가 예제나 라이브러리 기능을 제공할 예정입니다. 제거된 CKKS 행렬 곱셈 및 희소 인코딩 기능을 직접 대체하는 API는 없습니다.

9. CUDA 환경 변경

DESILO FHE 2.0에서는 CUDA 13.2와 CUDA 13.4만 지원합니다. 이전 CUDA 툴체인을 사용하는 프로그램은 빌드 및 실행 환경을 업데이트해야 합니다.

특히 CUDA 13.0은 중첩된 스레드 분기(thread divergence)가 있는 커널에서 잘못된 결과를 오류 없이 생성할 수 있는 컴파일러 버그로 인해 더 이상 지원되지 않습니다. 이 문제는 CUDA 12.8에서 처음 발생하였으며 CUDA 13.2.2에서 수정되었습니다. DESILO FHE에서 해당 문제가 발현된 적은 없지만, 예방적 조치로 영향을 받는 CUDA 버전의 지원을 중단하였습니다.

업그레이드할 때는 설치된 NVIDIA 드라이버가 선택한 CUDA 버전과 호환되는지 확인하시기 바랍니다.

10. 직렬화된 데이터 및 키 이전

DESILO FHE 2.0에서는 직렬화 형식이 전면 개편되었습니다. 이전 버전에서 직렬화한 데이터와 키는 2.0과 호환되지 않습니다.

프로그램에 필요한 데이터와 키를 새로 생성해야 합니다.

권장하는 이전 절차는 다음과 같습니다.

  1. 이전 버전의 라이브러리를 사용하여 기존 데이터를 읽어들입니다.
  2. 가능한 경우 원본 평문 데이터를 복원합니다.
  3. DESILO FHE 2.0으로 업그레이드합니다.
  4. 변경된 엔진 설정을 사용하여 새로운 키를 생성합니다.
  5. 원본 데이터를 다시 인코딩하고 암호화합니다.
  6. DESILO FHE 2.0을 사용하여 새로운 데이터와 키를 직렬화합니다.

원본 평문이 없는 경우 비밀 키와 이전 버전의 라이브러리가 필요할 수 있습니다. 이전 직렬화 형식을 새로운 형식으로 직접 변환하는 기능은 지원되지 않습니다.

마이그레이션 체크리스트

DESILO FHE 2.0을 사용하는 프로그램을 배포하기 전에 다음 항목을 확인하시기 바랍니다.

  • [ ] Engine 생성자의 모든 인자를 키워드 인자로 전달하도록 변경합니다.
  • [ ] use_bootstrap과 use_multiparty를 새로운 이름으로 변경합니다.
  • [ ] 기존 rotate 호출을 검토하고 필요한 경우 roll로 변경합니다.
  • [ ] 회전 키를 순환 키로 변경합니다.
  • [ ] 고정 회전 키를 고정 순환 키로 변경합니다.
  • [ ] 순환 관련 함수의 delta 인자를 shift로 변경합니다.
  • [ ] 고정 순환 키 생성 시 level을 키워드 인자로 전달하도록 변경합니다.
  • [ ] GL의 hadamard_multiply 호출을 multiply로 변경합니다.
  • [ ] GL의 아다마르 곱셈 키를 재선형화 키로 변경합니다.
  • [ ] 부트스트랩에 17레벨 설정을 사용하도록 변경합니다.
  • [ ] 지원이 중단된 CKKS 행렬 곱셈 및 희소 인코딩 기능을 더 이상 사용하지 않습니다.
  • [ ] CKKS와 GL에 지원되는 형상과 파라미터를 사용합니다.
  • [ ] CUDA 환경을 지원되는 버전으로 변경합니다.
  • [ ] 이전에 직렬화한 데이터와 키를 새로운 형식으로 이전합니다.
  • [ ] 테스트를 다시 실행하여 연산 결과의 정확도를 확인합니다.

DESILO FHE 2.0의 변경 사항에 대한 자세한 내용은 릴리스 노트를 참고하시기 바랍니다.