publicproj/aio-01d4-stu

0 Fork 0

Files

T

mcchae 19969d1d44 PPTX=>MD, 머메이드 뷰어 사이트 수정

2026-10-13 16:24:23 +09:00

9.9 KiB

Raw Blame History

64일차 실습 준비 · 수업 전에 미리 해 두면 좋은 것

수업일: 2026-10-14 (64일차) · AI 워크플로우 개념 및 구성 요소 이해
준비 시간: 약 1시간 (대체용 Ollama 모델을 새로 받는 경우. 이미 있으면 약 30분)
가장 먼저 0절(수업 저장소 받기) 을 하고, 수업 전날까지 1~~2절을 끝내 주세요. 3~~4절은 시간이 될 때 읽어 오면 수업이 훨씬 쉬워집니다.

flowchart LR
  Z["0. 수업 저장소 받기<br/>git clone"] --> A
  A["1. 실습 환경<br/>WSL · uv · API 키<br/>(대체: Ollama)"] --> B["2. 확인 명령<br/>pytest · check"]
  B --> C["3. 미리 읽기<br/>JSON · 지난 실습"]
  C --> D["4. 생각해 오기<br/>내 업무 시나리오"]

0. 가장 먼저: 수업 저장소 받기 (2분)

실습 코드와 안내 문서는 모두 공개 저장소 https://gl.isitsoft.kr/publicproj/aio-01d4-stu 에 있습니다. 공개(public) 저장소라 계정·로그인 없이 누구나 받을 수 있습니다. WSL(Ubuntu) 터미널을 열고 홈 폴더에서 아래 명령을 실행합니다.

cd ~
git clone https://gl.isitsoft.kr/publicproj/aio-01d4-stu.git
cd ~/aio-01d4-stu && ls          # Last3Mon  Lecture 가 보이면 성공

이 문서와 앞으로의 안내에 나오는 폴더는 모두 ~/aio-01d4-stu 기준입니다.
앞으로 매일 수업 전에 cd ~/aio-01d4-stu && git pull로 새 자료를 받습니다.
사용자 이름·비밀번호를 묻는다면 주소 오타입니다. 주소를 다시 확인하세요. git: command not found가 나오면 sudo apt update && sudo apt install -y git 후 다시 실행합니다.
WSL이 아직 준비되지 않았다면 안내서 1절(WSL 확인)을 먼저 한 뒤 이 명령을 실행합니다.

1. 실습 환경 준비 (전날 필수, 약 40분)

오늘 실습은 Windows 11 노트북의 WSL(Ubuntu) 에서 진행합니다. LLM은 과정에서 받은 키로 OpenAI API(gpt-4.1-mini)를 씁니다. 이 구성은 65일차 이후에도 그대로 씁니다.

Ollama는 대체용입니다. OpenAI API 키가 작동하지 않을 때(키 오류, 사용 한도 초과, 인터넷 끊김)만 노트북에서 직접 실행하는 Ollama(gemma3:4b)가 대신 답합니다. 평소 실습에는 쓰지 않지만, 수업 중에 키가 막히면 바로 넘어갈 수 있도록 전날 미리 준비해 둡니다.

flowchart LR
  W["워크플로우의 LLM 노드"] -->|"기본"| O["OpenAI API<br/>gpt-4.1-mini"]
  W -.->|"키가 작동하지 않을 때만"| L["Ollama (노트북)<br/>gemma3:4b / gemma3:1b"]

자세한 순서는 사전 준비 안내 (SETUP-WSL-LLM) 를 따라 하세요. 할 일만 요약하면 다음과 같습니다.

순서	할 일	시간
1	WSL(Ubuntu) 동작 확인	5분
2	uv 설치 (수업 저장소는 0절에서 이미 받음)	10분
3	`Last3Mon/.env`에 OpenAI API 키 넣기	3분
4	노트북 메모리 확인 → 대체 모델 결정 (8GB: `gemma3:1b`, 16GB 이상: `gemma3:4b`)	2분
5	(대체용) Ollama가 이미 있는지 확인 → 없을 때만 설치와 모델 다운로드	1분 / 10~20분
6	연결 확인 (OpenAI, 대체 Ollama)	5분

5단계 전에: Ollama를 이미 쓸 수 있는지 먼저 확인

8~9월 Ollama 실습에서 이미 설치해 둔 분이 많습니다. 새로 설치하기 전에 WSL 터미널에서 아래 명령으로 확인합니다.

ollama --version     # 버전이 나오면 Ollama 설치됨
ollama list          # gemma3:4b (8GB 노트북은 gemma3:1b)가 보이면 모델도 준비됨

결과	할 일
버전과 모델이 모두 보임	설치·다운로드를 건너뛰고 6단계(연결 확인)로
버전은 나오지만 모델이 없음	모델만 받기: `ollama pull gemma3:4b` (8GB 노트북은 `gemma3:1b`)
`command not found`	안내서 5절대로 설치. 단, Windows나 Docker에 Ollama가 이미 있으면 안내서 7절을 먼저 확인
`ollama list`에서 연결 오류	다른 터미널에서 `ollama serve` 실행 후 다시 확인

설치·다운로드가 필요한 경우, Ollama 모델 파일이 1~3GB라서 수업 중에 여러 명이 동시에 받으면 강의실 네트워크가 매우 느려집니다. 다운로드는 꼭 집에서 미리 해 주세요.

2. 준비가 끝났는지 확인 (전날 필수, 5분)

WSL 터미널에서 실습 폴더로 이동해 아래 두 명령을 실행합니다.

cd ~/aio-01d4-stu/Last3Mon/64/workflow-lab
uv run pytest -q          # 18 passed, 1 skipped 가 나오면 성공
uv run miniflow check     # Reply (openai, ...) 가 나오면 성공
OPENAI_API_KEY=sk-wrong uv run miniflow check   # Reply (ollama, ...) 가 나오면 대체도 준비 완료

결과	의미
세 명령 모두 성공	준비 완료
`pytest`는 성공, 첫 `check`가 실패	`.env`의 키 문제. 안내서 8절(문제 해결) 확인
첫 `check`는 성공, 두 번째가 실패	대체용 Ollama 문제. 수업은 OpenAI로 할 수 있으니 1교시 전에 말씀해 주세요
모두 실패	uv 또는 저장소 위치 문제. 안내서 2절부터 다시 확인

해결이 안 되면 수업 당일 1교시 전에 말씀해 주세요. 키를 아직 못 받았으면 .env의 MINIFLOW_LLM=ollama로, 둘 다 안 되면 export MINIFLOW_LLM=mock으로 Mock LLM을 써서 실습을 따라올 수 있습니다.

3. 미리 읽어 오면 좋은 내용 (선택, 약 15분)

3.1 JSON 기초: 오늘 워크플로우를 적는 형식

오늘 실습에서는 워크플로우를 JSON 파일로 적습니다. JSON은 데이터를 "이름: 값" 짝으로 적는 형식입니다. 지난 실습에서 FastAPI 요청·응답이나 Pydantic 모델로 이미 여러 번 본 형식입니다.

{
  "name": "날씨 안내",
  "inputs": ["city"],
  "nodes": [
    {"id": "start", "type": "input"},
    {"id": "weather", "type": "tool", "tool": "get_weather", "args": {"city": "{{input.city}}"}}
  ],
  "edges": [["start", "weather"]]
}

기호	뜻	위 예시에서
`{ }`	객체: "이름": 값 짝의 묶음	노드 하나 `{"id": "start", ...}`
`[ ]`	목록: 여러 값을 순서대로	`"nodes": [ ... ]` 노드 목록
`"이름": 값`	이름과 값 한 쌍	`"type": "tool"`
`,`	항목 사이 구분	마지막 항목 뒤에는 쓰지 않음

자주 하는 실수

문자는 반드시 큰따옴표 "로 감쌉니다. 작은따옴표 '는 JSON에서 쓸 수 없습니다.
마지막 항목 뒤에 쉼표를 붙이면 오류가 납니다. {"a": 1, "b": 2,} (X)
괄호 { }, [ ]의 짝이 맞아야 합니다. VS Code에서 괄호를 클릭하면 짝이 강조됩니다.

3.2 지난 실습 떠올리기

오늘 배우는 노드는 모두 지난 3개월 동안 코드로 만들어 본 것들입니다. 아래 표의 실습을 한 번 떠올려 보세요.

오늘의 노드	지난 실습	떠올릴 것
LLM 노드	10일차 LLM API(OpenAI/Anthropic/Gemini) 호출, 27일차 Structured Output	프롬프트를 보내고 답을 받는 흐름, 정해진 형식으로 답 받기
Tool 노드	29~31일차 Tool Use·MCP (`mini_agent_03_tool`, `mini_agent_03_mcp`)	외부 기능(날씨 조회 등)을 호출해 결과를 받는 흐름
Memory 노드	35·39일차 Memory (`mini_agent_05_memory`)	사용자 선호·이력을 저장하고 다음 요청에 다시 쓰는 흐름
실행 순서·병렬	48일차 분산 협업 (`mini_multi_agent_04`)	여러 Agent를 동시에 실행하고 결과를 합치는(Join) 흐름
로컬 LLM	8~9월 Ollama 실습 (`llama3.2`, `gemma3:4b`)	노트북에서 모델을 실행하는 방법

3.3 용어 미리 보기

용어	한 줄 뜻
워크플로우	업무를 정해진 순서의 단계로 나누어 실행하는 흐름
노드	워크플로우에서 한 가지 일을 하는 단계 하나
연결(Edge)	노드 사이의 실행 순서와 데이터가 지나가는 길
페이로드	노드 사이를 오가는 데이터
실행 기록(Trace)	실행할 때마다 남는 노드별 입력·출력·시간 기록

4. 생각해 오기 (선택, 5분)

5~6교시 Lab 03에서 업무 하나를 골라 자동화 시나리오로 분석합니다. 아래 질문에 대한 답을 하나 생각해 오면 실습 시간을 아낄 수 있습니다.

학교·회사·아르바이트·일상에서 자주 반복하는 일 중 하나는 무엇인가요?
그 일은 어떤 순서로 진행되나요? (예: 메일 확인 → 내용 분류 → 자료 찾기 → 답장)
그중 판단이 필요한 단계와 정해진 규칙대로 하는 단계는 각각 어디인가요?

떠오르지 않으면 수업에서 제시하는 예시 시나리오 5개 중 하나를 골라도 됩니다.

5. 당일 준비물

충전된 노트북과 충전기 (대체용 Ollama는 배터리를 많이 사용합니다)
Windows Terminal (WSL 터미널), VS Code
웹 브라우저 (워크플로우 그림 확인용 Mermaid Viewer)
과정에서 받은 OpenAI API 키 (Last3Mon/.env에 넣어 오기). 키는 채팅·문서·화면 캡처에 올리지 않습니다
(선택) Anthropic·Gemini 키가 있으면 (예: 10일차에 발급한 Gemini 키) 같은 워크플로우를 다른 제공사 모델로도 비교해 볼 수 있습니다

확인

git clone으로 ~/aio-01d4-stu를 받았다
uv run pytest -q → 18 passed, 1 skipped
uv run miniflow check → Reply (openai, ...)
ollama list에 대체 모델(gemma3:4b 또는 gemma3:1b)이 보인다 (이미 있으면 새로 받지 않음)
OPENAI_API_KEY=sk-wrong uv run miniflow check → Reply (ollama, ...)
JSON 기초(3.1)를 읽었다
Lab 03에서 분석할 업무 후보를 하나 생각했다

9.9 KiB Raw Blame History