Langfuse 워크숍 - AI 엔지니어링 루프, 처음부터 끝까지
이것은 작은 TypeScript 샘플 애플리케이션인 Dad IT Support Agent를 기반으로 한 단계별 Langfuse 워크숍입니다. 이 워크숍은 Langfuse를 사용한 전체 AI 엔지니어링 루프를 다룹니다...
워크숍 자료는 공개 langfuse/langfuse-workshop 저장소에서 관리됩니다. 저장소를 사용하여 실행 가능한 앱, 체크포인트 분기, 로컬 설정을 확인하세요.
이것은 작은 TypeScript 샘플 애플리케이션인 Dad IT Support Agent를 기반으로 한 단계별 Langfuse 워크숍입니다. 이 워크숍은 Langfuse를 사용한 전체 AI 엔지니어링 루프를 다룹니다: 트레이싱, 프롬프트 관리, 모니터링, 데이터셋, 실험, 평가.
학습자 강의에서 워크숍을 독립적으로 완료하거나 강사 노트를 사용하여 같은 자료를 그룹에 가르칠 수 있습니다.
학습자를 위한 안내
docs/learner/의 학습자 강의로 시작하세요. 각 강의는 어느 체크포인트를 확인해야 하는지, 코드에서 무엇을 변경하거나 Langfuse에서 설정해야 하는지, 결과를 확인하는 방법을 알려줍니다.
다음 경우에 학습자 경로를 사용하세요:
- 실제 LLM 앱에서 첫 번째 트레이스를 로깅하고 보고 있는 것을 이해합니다.
- 프롬프트를 Langfuse로 이동하여 변경 사항이 버전 관리되고 트레이스에 연결됩니다.
- 모든 트레이스를 손으로 읽지 않고 프로덕션 동작을 모니터링합니다.
- 데이터셋을 구축하고, 실험을 실행하고, 증거를 통해 변경 사항을 평가합니다.
- 패턴을 복사할 수 있는 완전한 TypeScript 참조 구현을 검사합니다.
강사가 필요하지 않습니다. 학습자 강의는 자율 학습 모드로 워크숍을 실행하기에 충분히 완전합니다.
강사를 위한 안내
강사 가이드는 다른 사람들에게 Langfuse를 가르치고 싶은 사람들을 위한 것입니다. docs/instructor/의 노트를 라이브 워크숍을 진행하거나, 둘러보기를 녹화하거나, 팀을 위해 자료를 조정할 때 학습자 강의와 함께 사용하세요.
준비를 위해 워크숍 준비 방법에 대한 가이드와 슬라이드를 포함했습니다 docs/preparation_and_materials/.
워크숍은 강사에게 의존하지 않습니다. 강사 노트는 교육 지점, 데모 리듬, 설정 알림 및 일반적인 함정을 추가합니다. 이들은 워크숍을 혼자 완료하는 사람에게 필수적이지 않습니다.
워크숍 범위
샘플 앱은 Dad가 iPhone 도움을 받기 위해 채팅을 여는 작은 웹 채팅입니다. 에이전트의 이름은 Specs이며 단계별 지시를 제공합니다. 내부적으로 두 개의 로컬 도구가 있는 일반적인 OpenAI 도구 호출 루프입니다.
main은 완전한 참조 앱과 현재 워크숍 문서를 포함합니다. 완성된 구현을 검사하거나 작업을 최종 상태와 비교하는 데 사용하세요. 연습 자체는 체크포인트 태그에서 시작합니다.
모듈
| 단계 | 학습자 강의 | 강사 노트 | 체크포인트 | 배우게 될 내용 |
|---|---|---|---|---|
| 00 | 설정 | 강사 노트 | checkpoint/00-setup | 키, 설치, 앱 실행. |
| 01 | 기본 앱 | 강사 노트 | checkpoint/01-base-app | 실행 중인 앱 둘러보기. 구축할 것이 없습니다. |
| 02 | 트레이싱 | 강사 노트 | checkpoint/02-tracing | 모든 에이전트 단계 로깅: 생성, 에이전트 루트, 도구 스팬. |
| 03 | 프롬프트 관리 | 강사 노트 | checkpoint/03-prompt-management | 시스템 프롬프트를 Langfuse로 이동. |
| 04 | 모니터링 | 강사 노트 | checkpoint/04-monitoring | 범위 밖의 요청과 사용자 의견 일치 감지. |
| 05 | 데이터셋 | 강사 노트 | checkpoint/05-dataset | 제품 범위를 재사용 가능한 예제로 변환. |
| 06 | 실험 | 강사 노트 | checkpoint/06-experiments | 데이터셋에 대해 에이전트를 실행하고 모든 항목을 점수화. |
| 07 | 평가 | 강사 노트 | checkpoint/07-evaluation | 한 가지를 변경하고, 데이터셋을 다시 실행하고, 실행을 비교. |
| 08 | 마무리 | 강사 노트 | checkpoint/08-wrap-up | 루프를 자신의 앱에 적용. |
진행 방법
main는 완전한 참조 구현입니다. 실습을 위해 시작하는 강의에서 이름이 지정된 체크포인트를 확인하고, 누락된 변경을 수행한 다음, 계속하기 전에 결과를 확인하세요.
checkpoint/00-setup와 checkpoint/01-base-app은 의도적으로 동일한 추적되지 않은 기본 앱을 포함합니다. 설정은 해당 상태를 사용하여 키, 종속성 및 포트를 검증합니다. 기본 앱은 방향 설정에 사용합니다. 트레이싱은 02-tracing에서 시작합니다.
워크숍 서버 및 npm 헬퍼 스크립트는 저장소 .env을 Node 측 소스의 진실로 취급합니다. 다른 프로젝트의 로컬 셸 내보내기는 .env를 재정의하지 않으므로 해당 파일에서 워크숍 키, Langfuse 호스트, 프롬프트 레이블 및 데이터셋 이름을 변경하세요.
워크숍은 한 번의 앉음으로 완료할 수 있을 정도로 작으며, 모든 모듈은 루프의 한 부분만 관심이 있는 경우 독립적으로도 사용할 수 있습니다.
저장소 레이아웃
docs/learner/은 자율 학습 워크숍 강의를 포함합니다.docs/instructor/은 동일한 강의를 가르치기 위한 진행자 노트를 포함합니다.docs/images/은 강의별로 그룹화된 스크린샷과 다이어그램을 포함합니다.src/은 샘플 앱을 포함합니다.scripts/은 나중 강의에서 사용되는 데이터셋 및 프롬프트 헬퍼 스크립트를 포함합니다.
다음 진행 방법
docs/learner/00-setup.md에서 시작하여 모듈을 순서대로 진행하세요.- 배우고 싶은 것과 일치하는 장으로 건너뛰세요.
- Langfuse 스킬 (
/langfuse)을 설치하여 이 워크숍의 패턴을 자신의 코드베이스에 적용하세요. - 각 장의 큰 그림 자료는 Langfuse 아카데미를 사용하세요.