jmedia65/learn-ai-right

프레임워크 없이 AI의 기초를 배우세요. 오직 Python, API, 그리고 명확함만 있습니다.

제가 AI 개발을 배우기 시작했을 때, 다양한 프레임워크와 라이브러리에 대한 끝없는 튜토리얼들을 발견했습니다. 하지만 무언가 고장 났을 때, 내부(under the hood)에서 실제로 어떤 일이 일어나고 있는지 전혀 알 수 없었습니다. 문제를 디버깅(debug)하거나, 성능을 최적화(optimize)하거나, 정보에 기반한 아키텍처 결정(architectural decisions)을 내릴 수 없었습니다.

이 코스는 그 간극을 채워줍니다. 추상화(abstractions)와 마케팅 용어(marketing jargon)를 걷어내고, AI 시스템이 실제로 무엇을 하는지 가르쳐줍니다. 여러분은 모든 AI 애플리케이션이 — 그것을 인정하든 안 하든 — 사용하는 기초적인 패턴(foundational patterns)을 배우게 될 것입니다.

프레임워크는 그 나름의 용도가 있습니다. 저도 프레임워크를 사용합니다. 여러 개를 좋아하기도 합니다. 하지만 기초를 이해하지 못한 채 프레임워크로 뛰어드는 것은 비효율적입니다. 불안정한 지반 위에 건물을 짓는 것과 같습니다.

이 코스는 여러분이 다음과 같은 작업을 수행할 때 실제로 어떤 일이 일어나는지 가르쳐줍니다:

• AI와 채팅하기
• AI에게 메모리(memory) 부여하기
• AI가 도구(tools)를 사용하게 만들기
• AI가 문서를 검색하게 만들기
• 다단계 워크플로(multi-step workflows) 구축하기

이러한 패턴을 이해하고 나면, 어떤 프레임워크든 효과적으로 사용할 수 있거나, 프레임워크 없이도 정확히 필요한 것을 직접 구축할 수 있습니다.

업계는 복잡한 용어를 좋아합니다. 하지만 실제로는 다음과 같습니다:

업계 용어	실제 정체
AI Agents (AI 에이전트)	AI가 호출하기로 결정한 Python 함수들
Memory/Context (메모리/컨텍스트)	각 요청과 함께 보내는 메시지들의 Python 리스트
RAG (Retrieval Augmented Generation, 검색 증강 생성)	관련 텍스트 검색 + 프롬프트(prompt)에 추가 + AI에게 질문
Multi-Agent Systems (멀티 에이전트 시스템)	로직을 사이에 둔 순차적인 API 호출
Embeddings/Vector DBs (임베딩/벡터 DB)	대규모 데이터셋에는 유용하지만, 대부분의 경우에는 키워드 검색으로도 충분함
Prompt Chaining (프롬프트 체이닝)	AI 호출 → 결과 처리 → 다시 AI 호출

그게 전부입니다. 마법은 없습니다. 그저 API 호출과 기본적인 프로그래밍일 뿐입니다.

이 코스는 이제 깔끔한 **10단계 정석 경로(10-step canonical path)**를 따릅니다:

First AI Call (첫 번째 AI 호출) - 모든 AI 애플리케이션이 사용하는 기본 패턴
Memory as List (리스트로서의 메모리) - 챗봇 뒤에 숨겨진 상태 비저장(stateless)의 진실
Memory with previous_response_id (previous_response_id를 활용한 메모리) - OpenAI의 편리한 체이닝(chaining)

Structured Outputs (구조화된 출력) - 모델 출력을 타입이 지정되고 검증된 데이터로 변환
Tool Calling (도구 호출) - 함수를 통해 AI가 직접 행동을 수행하도록 함
RAG (검색 증강 생성) - 사용자의 문서를 바탕으로 AI가 질문에 답변하도록 함
Conversational RAG (대화형 RAG) - 문서 기반 질의응답(Q&A)에 후속 질문 기능을 추가
Streaming (스트리밍) - AI의 응답을 실시간으로 단어 단위로 표시
Prompt Chaining (프롬프트 체이닝) - 다단계 AI 워크플로우(workflows) 구축
Capstone (OpenAI 전용) - 모든 요소를 결합한 하나의 엔드투엔드(end-to-end) 프로젝트

이 과정을 마치면, 실제 운영되는 AI 시스템이 내부적으로 어떻게 작동하는지 이해하게 될 것입니다.

• OpenAI 예제는 새로운 프로젝트에 권장되는 기본 API인 Responses API(client.responses.create(...))를 사용합니다.
• Anthropic 예제는 현재의 messages API 패턴을 사용합니다.
• 모델은 환경 변수(env vars)를 통해 설정할 수 있습니다: OPENAI_MODEL (예제 기본값: gpt-4.1), ANTHROPIC_MODEL (예제 기본값: claude-sonnet-4-6)

당신은 오직 Python만 알면 됩니다. 그게 전부입니다.

머신러닝(machine learning) 배경지식도, 고급 수학 지식도, 프레임워크 경험도 필요 없습니다.

함수(functions)와 루프(loops)를 작성할 수 있고, 리스트(lists)와 딕셔너리(dictionaries)를 이해할 수 있다면 준비가 된 것입니다.

1. 이 저장소(repository)를 클론(Clone)하세요

git clone https://github.com/jmedia65/learn-ai-right.git
cd learn-ai-right

2. 의존성(dependencies)을 설치하세요

pip install -r requirements.txt

3. API 키를 설정하세요

.env.example 파일을 .env로 복사하세요:

cp .env.example .env

.env 파일에 API 키를 추가하세요:

ANTHROPIC_API_KEY=your_anthropic_key_here
OPENAI_API_KEY=your_openai_key_here
# 선택 사항:
...

API 키 발급처:

• Anthropic: https://console.anthropic.com/
• OpenAI: https://platform.openai.com/api-keys

4. 첫 번째 모듈부터 시작하세요

cd 01-first-ai-call
python 01_anthropic_basic.py

각 모듈은 다음을 포함합니다:

• 개념을 설명하는 README
• OpenAI 예제 (모든 단계)
• Anthropic 보조 예제 (대부분의 단계)
• 정확히 어떤 일이 일어나는지 보여주는 주석이 상세히 달린 코드
• 의도적인 연습을 위한 Quick Exercise (빠른 연습) 및 What Breaks in Production (실제 운영 시 발생하는 문제) 섹션

순서대로 진행하세요:

기초적인 패턴을 학습합니다: 초기화(initialize) → 호출(call) → 응답 추출(extract response).

챗봇이 문맥(context)을 기억하는 방식을 이해합니다 (스포일러: 그저 리스트일 뿐입니다).

리스트 기반 메모리(list-based memory)를 마스터한 후, OpenAI의 상태 체이닝(state-chaining) 편의 API를 학습합니다.

브릿지 모듈: 도구 호출(tool calling) 전에 타입이 지정되고 검증된 출력(typed, validated outputs)을 얻는 방법을 배웁니다.

여러분의 Python 함수를 호출하여 AI가 직접 행동을 취하게 만듭니다.

여러분의 문서로부터 AI가 질문에 답하게 만듭니다.

문서 기반 질의응답(Q&A) 시스템에 후속 질문(follow-up questions) 기능을 추가합니다.

AI의 응답을 실시간으로, 단어 단위로(word by word) 표시합니다.

다단계 AI 워크플로(workflows) 및 "에이전트(agent)" 시스템을 구축합니다.

메모리, 구조화된 출력(structured outputs), 도구(tools), RAG, 스트리밍(streaming), 그리고 체이닝(chaining)을 결합한 하나의 완전한 AI 러닝 코치(AI Learning Coach)를 구축합니다.

저는 Max Braglia이며, maxbraglia.substack.com에서 AI 엔지니어링에 관한 글을 씁니다. 제가 AI 개발을 배우기 시작했을 때 이런 과정이 있었으면 좋았겠다는 생각에 이 코스를 만들었습니다.

MIT License - 이 코드를 원하는 대로 사용하세요. 배우고, 구축하고, 다른 사람들에게 가르치세요.