PacktPublishing/LLM-Engineers-Handbook

Amazon 또는 Packt에서 이 책을 찾아보세요.

이 책의 목표는 모범 사례를 사용하여 자체적인 엔드투엔드(end-to-end) LLM 기반 시스템을 구축하는 것입니다:

• 📝 데이터 수집 및 생성 (Data collection & generation)
• 🔄 LLM 학습 파이프라인 (LLM training pipeline)
• 📊 간단한 RAG 시스템 (Simple RAG system)
• 🚀 프로덕션 준비가 된 AWS 배포 (Production-ready AWS deployment)
• 🔍 포괄적인 모니터링 (Comprehensive monitoring)
• 🧪 테스트 및 평가 프레임워크 (Testing and evaluation framework)

최종 학습된 모델은 Hugging Face에서 다운로드하여 사용할 수 있습니다.

중요 사항

이 GitHub 저장소의 코드는 활발하게 유지 관리되고 있으며, 책에 반영되지 않은 업데이트가 포함될 수 있습니다. 항상 최신 버전의 코드를 확인하려면 이 저장소를 참조하십시오.

프로젝트를 로컬에서 설치하고 실행하려면 다음 종속성(dependencies)이 필요합니다.

| Service | Purpose |
|---|---|---|
| HuggingFace | 모델 레지스트리 (Model registry) |
| ... |
이 LLM Engineer's Handbook의 Chapter 2에서는 각 도구에 대해 안내합니다. Chapter 10과 11은 필요한 모든 것을 설정하는 방법에 대한 단계별 가이드를 제공합니다.

디렉터리 개요는 다음과 같습니다:

.
├── code_snippets/ # 독립적인 예제 코드 (Standalone example code)
├── configs/ # 파이프라인 구성 파일 (Pipeline configuration files)
...

llm_engineering/

은 LLM 및 RAG 기능을 구현하는 주요 Python 패키지입니다. 이 패키지는 Domain-Driven Design (DDD) 원칙을 따릅니다:

domain/
: 핵심 비즈니스 엔티티 및 구조 (Core business entities and structures)
application/
: 비즈니스 로직, 크롤러, RAG 구현 (Business logic, crawlers, and RAG implementation)
model/
: LLM 학습 및 추론 (LLM training and inference)
infrastructure/
: 외부 서비스 통합 (AWS, Qdrant, MongoDB, FastAPI)

코드 로직과 임포트는 다음과 같이 흐릅니다: infrastructure
→ model
→ application
→ domain

pipelines/

다음과 같이 구성되어 있습니다:

infrastructure
→ model
→ application
→ domain

pipelines/
: 모든 ML 파이프라인의 진입점 역할을 하는 ZenML ML 파이프라인을 담고 있습니다. ML 라이프사이클의 데이터 처리 및 모델 훈련 단계를 조정합니다.

steps/
: ZenML 파이프라인 구축 및 사용자 정의를 위한 재사용 가능한 구성 요소인 개별 ZenML 스텝(step)들을 포함하고 있습니다. 스텝은 특정 작업(예: 데이터 로딩, 전처리)을 수행하며 ML 파이프라인 내에서 결합될 수 있습니다.

tests/
: CI 파이프라인 내 예시로 사용되는 몇 가지 샘플 테스트를 다룹니다.

tools/
: ZenML 파이프라인 및 추론 코드를 호출하는 데 사용되는 유틸리티 스크립트들입니다:

run.py
: ZenML 파이프라인을 실행하기 위한 진입점(entry point) 스크립트입니다.
ml_service.py
: REST API 추론 서버를 시작합니다.
rag.py
: RAG 검색 모듈의 사용법을 시연합니다.
data_warehouse.py
: JSON 파일을 통해 MongoDB 데이터 웨어하우스에서 데이터를 내보내거나 가져오는 데 사용됩니다.

configs/
: 파이프라인 및 스텝 실행을 제어하는 ZenML YAML 설정 파일들입니다.

code_snippets/
: 독립적으로 실행할 수 있는 개별 코드 예제들입니다.

참고

저장소 설치 및 실행 중 문제가 발생하면, GitHub Issues 섹션에서 유사한 문제를 해결한 다른 사람들의 내용을 확인하거나 직접 도움을 요청하는 것을 고려해 보세요.

먼저 저장소를 클론하고 프로젝트 디렉터리로 이동합니다:

git clone https://github.com/PacktPublishing/LLM-Engineers-Handbook.git
cd LLM-Engineers-Handbook

다음으로, Python 환경과 그 주변 종속성(dependencies)을 준비해야 합니다.

이 프로젝트는 Python 3.11을 요구합니다. 전역 Python 설치를 사용하거나 pyenv를 사용하여 프로젝트별 버전을 설정할 수 있습니다.

Python 버전 확인:

python --version # Python 3.11.x가 표시되어야 합니다

• pyenv 설치 확인:

pyenv --version # pyenv 2.3.36 이상이 표시되어야 합니다

• Python 3.11.8 설치:

pyenv install 3.11.8

• 설치 확인:

python --version # Python 3.11.8이 표시되어야 합니다

• 프로젝트 디렉터리에서 Python 버전 확인:

python --version
# 출력: Python 3.11.8

참고

이 프로젝트에는 .python-version 파일이 포함되어 있어, 프로젝트 디렉터리에서 작업할 때 올바른 Python 버전을 자동으로 설정합니다.

이 프로젝트는 의존성 관리를 위해 Poetry를 사용합니다.

• Poetry 설치 확인:

poetry --version # Poetry 버전 1.8.3 이상이어야 합니다

• 프로젝트 환경 설정 및 의존성 설치:

poetry env use 3.11
poetry install --without aws
poetry run pre-commit install

이 명령어들은 다음을 수행합니다:

• Poetry가 Python 3.11을 사용하도록 구성합니다.
• 프로젝트 의존성을 설치합니다 (AWS 관련 패키지 제외).
• 코드 검증을 위한 pre-commit hook을 설정합니다.

저희는 작업 관리자로서 모든 스크립트를 Poe the Poet를 사용하여 실행합니다.

• Poetry 셸 시작:

poetry shell

• Poe the Poet를 사용하여 프로젝트 명령어 실행:

poetry poe ...

🔧 Poe the Poet 설치 문제 해결

만약 poethepoet 사용에 문제가 있다면, 여전히 Poetry를 통해 직접 프로젝트 명령을 실행할 수 있습니다. 방법은 다음과 같습니다:

• pyproject.toml에서 명령어 정의를 찾습니다.
• 기본 명령어와 함께 poetry run을 사용합니다.

예시:
대신에:
poetry poe local-infrastructure-up

pyproject.toml의 직접 명령어를 사용하세요:
poetry run <pyproject.toml에서 가져온 실제 명령어>

참고: 모든 프로젝트 명령어는 pyproject.toml의 [tool.poe.tasks] 섹션에 정의되어 있습니다.

이제 필요한 자격 증명과 토큰을 모두 갖추어 로컬 프로젝트를 구성해 보겠습니다.

모든 의존성을 설치한 후에는, 다른 서비스와 적절하게 상호 작용하고 프로젝트를 실행하기 위해 반드시 .env 파일을 생성하고 사용자 자격 증명을 채워야 합니다. 민감한 자격 증명을 .env 파일에 설정하는 것은 좋은 보안 관행이며, 이 파일은 GitHub에 커밋되거나 다른 사람과 공유되지 않습니다.

• 먼저 다음 명령을 실행하여 예시 파일을 복사합니다:

cp .env.example .env # 이 파일은 리포지토리의 루트에 있어야 합니다!

• 이제 .env 내의 모든 필수 변수를 어떻게 채워야 하는지 알아보겠습니다.

시작하는 데 필요한 파일을 확인하세요. 다음은 로컬에서 작업할 때 반드시 완료해야 하는 필수 설정들입니다:

OpenAI API에 인증하려면 OPENAI_API_KEY 환경 변수에 인증 토큰을 채워야 합니다.

OPENAI_API_KEY=your_api_key_here

→ OpenAI에서 토큰을 받는 방법을 배우려면 이 튜토리얼을 확인하세요.

Hugging Face에 인증하려면 HUGGINGFACE_ACCESS_TOKEN 환경 변수에 인증 토큰을 채워야 합니다.

HUGGINGFACE_ACCESS_TOKEN=your_token_here

→ Hugging Face에서 토큰을 받는 방법을 배우려면 이 튜토리얼을 확인하세요.

Comet ML(훈련 중에만 필요) 및 Opik에 인증하려면 COMET_API_KEY 환경 변수에 인증 토큰을 채워야 합니다.

COMET_API_KEY=your_api_key_here

→ Opik 사용법을 배우려면 이 튜토리얼을 확인하세요. 또한 🔗이 링크를 사용하여 Opik 대시보드에 접속할 수 있습니다.

프로젝트를 클라우드에 배포하려면 Mongo, Qdrant 및 AWS에 대한 추가 설정이 필요합니다. 로컬에서만 작업하는 경우, 이러한 환경 변수들의 기본값이 별도의 설정 없이 작동합니다. 자세한 배포 지침은 LLM Engineer's Handbook의 11장에서 확인할 수 있습니다.

DATABASE_HOST 환경 변수를 클라우드 MongoDB 클러스터를 가리키는 URL로 변경해야 합니다.

DATABASE_HOST=your_mongodb_url

→ 무료로 MongoDB 클러스터를 생성하고 호스팅하는 방법을 배우려면 이 튜토리얼을 확인하세요.

USE_QDRANT_CLOUD를 true로, QDRANT_CLOUD_URL에 클라우드 Qdrant 클러스터 URL을, 그리고 QDRANT_APIKEY에 API 키를 설정해야 합니다.

USE_QDRANT_CLOUD=true
QDRANT_CLOUD_URL=your_qdrant_cloud_url
QDRANT_APIKEY=your_qdrant_api_key

→ 무료로 Qdrant 클러스터를 생성하는 방법을 배우려면 이 튜토리얼을 확인하세요.

AWS 설정이 올바르게 작동하려면 로컬 머신에 AWS CLI가 설치되어 있고 관리자 사용자(또는 새로운 SageMaker, ECR 및 S3 리소스를 생성할 충분한 권한을 가진 사용자)로 적절하게 구성되어 있어야 합니다 (관리자 사용자를 사용하면 모든 것이 더 간단해집니다).

Chapter 2에서는 AWS CLI를 설치하고, AWS에서 관리자 사용자(admin user)를 생성하며, AWS_ACCESS_KEY 및 AWS_SECRET_KEY 환경 변수를 설정하기 위한 액세스 키를 얻는 단계별 지침을 제공합니다. 이미 AWS 관리자 사용자가 있는 경우, 다음 환경 변수들을 .env 파일에 구성해야 합니다:

AWS_REGION=eu-central-1 # 본인의 AWS 리전으로 변경하세요.
AWS_ACCESS_KEY=your_aws_access_key
AWS_SECRET_KEY=your_aws_secret_key

AWS 자격 증명(credentials)은 일반적으로 ~/.aws/credentials에 저장됩니다. 이 파일은 cat 또는 유사한 명령어를 사용하여 직접 확인할 수 있습니다:

cat ~/.aws/credentials

중요 사항 (Important)
추가적인 구성 옵션들은 settings.py에서 사용할 수 있습니다. Settings 클래스의 모든 변수는 .env 파일을 통해 설정할 수 있습니다.

로컬 환경에서 프로젝트를 실행할 때, MongoDB와 Qdrant 데이터베이스를 Docker를 사용하여 호스팅합니다. 또한, 테스트용 ZenML 서버가 해당 Python 패키지를 통해 제공됩니다.

경고 (Warning)
Docker가 설치되어 있어야 합니다 (>= v27.1.1)
사용 편의성을 위해 다음 명령어로 전체 로컬 개발 인프라를 시작할 수 있습니다:

poetry poe local-infrastructure-up

또한, 다음 명령어를 사용하여 ZenML 서버와 모든 Docker 컨테이너를 중지할 수 있습니다:

poetry poe local-infrastructure-down

경고 (Warning)
MacOS에서 실행할 때는 서버를 시작하기 전에 다음 환경 변수를 내보내야 합니다:
export OBJC_DISABLE_INITIALIZE_FORK_SAFETY=YES

그렇지 않으면 로컬 서버와 파이프라인 간의 연결이 끊어집니다. 🔗 자세한 내용은 이 이슈(issue)를 참고하세요.
이는 Poe the Poet을 사용할 때 기본적으로 수행됩니다.

추론 실시간 RESTful API 시작:

poetry poe run-inference-ml-service

중요 사항 (Important)
RESTful API에 의해 호출되는 LLM 마이크로서비스는 AWS SageMaker에 LLM을 배포한 후에만 작동합니다.

대시보드 URL: localhost:8237
기본 자격 증명:
username: default
password:
→ ZenML 사용 및 설정에 대해 더 알아보기.

REST API URL: localhost:6333
대시보드 URL: localhost:6333/dashboard

→ Docker를 사용하여 Qdrant 설정 및 사용에 대해 더 알아보기.

데이터베이스 URI: mongodb://llm_engineering:[email protected]:27017

데이터베이스 이름: twin

기본 자격 증명:

username: llm_engineering
password: llm_engineering

→ Docker를 사용하여 MongoDB 설정 및 사용에 대해 더 알아보기.

사용자는 IDE의 MongoDB 플러그인 (별도로 설치해야 함)을 사용하여 MongoDB 컬렉션을 검색할 수 있습니다. 이때 도커 컨테이너 내부에 호스팅된 MongoDB 데이터베이스에 연결하려면 다음 데이터베이스 URI를 사용해야 합니다: mongodb://llm_engineering:[email protected]:27017

중요 사항

LLM의 훈련 또는 실행(예: 훈련, 평가, 추론)과 관련된 모든 것은 다음 클라우드 인프라 섹션에서 설명하는 대로 AWS SageMaker를 설정해야만 실행할 수 있습니다.

여기서는 프로젝트를 AWS 및 기타 서버리스 서비스에 배포하는 방법을 간략하게 소개합니다. 자세한 내용은 다루지 않겠습니다 (모든 내용이 책에 제시되어 있으므로) 단지 거쳐야 할 주요 단계들만 알려드리겠습니다.

먼저, AWS 그룹을 사용하여 Python 종속성을 다시 설치하십시오:

poetry install --with aws

참고

제10장에는

AWS가 저희를 대신하여 다른 AWS 리소스에 접근하는 데 사용되는 IAM 실행 역할을 생성하려면 다음을 실행하십시오:

poetry poe create-sagemaker-execution-role

이 명령어는 새 AWS_ARN_ROLE 값을 포함하는 sagemaker_execution_role.json 파일을 리포지토리 루트에 생성합니다. 이 파일을 .env 파일에 추가하십시오.

.env 파일에서 AWS_ACCESS_KEY, AWS_SECRET_KEY, 그리고 AWS_ARN_ROLE 값을 업데이트했으면 AWS SageMaker를 사용할 수 있습니다. 이 단계는 AWS 설정을 완료하는 데 매우 중요합니다.

다음과 같이 실행하여 ZenML을 통해 트레이닝 파이프라인을 시작합니다:

poetry poe run-training-pipeline

이렇게 하면 configs/training.yaml의 설정에서 직접 SageMaker를 사용하여 트레이닝 코드를 시작하게 됩니다. 결과를 Comet ML 대시보드에서 시각화할 수 있습니다.