๋ฒ์ :
v1.0.0ยท ๊ถ์ฅ Python:3.13
GitHub ์ ์ฅ์์ ์ฝ๋๋ฅผ ๊ฒ์ ๊ฐ๋ฅํ ์ง์์ผ๋ก ๋ง๋ค๊ณ , ๊ฒ์๋ ์ฝ๋๋ง ๊ทผ๊ฑฐ๋ก ๋ต๋ณํ๋ Django ์ฑ๋ด ์ค์ต์ ๋๋ค. ๋ณต์กํ GitHub ์์งยท๋ณด์ยทChroma ๊ต์ฒด ๋ก์ง์ ์์ฑ๋ ์ํ๋ก ์ ๊ณต๋๋ฉฐ, ์ค์ต์์๋ ์ฑํ ๋ฉ์์ง๊ฐ ๋ต๋ณ๊ณผ ์ถ์ฒ๋ก ๋์์ค๊ธฐ๊น์ง์ ์ฌ์ฏ ํจ์๋ฅผ ์์ฑํฉ๋๋ค.
๋ธ๋ผ์ฐ์ ๋ฉ์์ง
โ Django POST API
โ ๋ํ ์๋น์ค
โ Vector DB ๊ฒ์
โ ๊ฒ์ ๊ฒฐ๊ณผ๋ฅผ Context๋ก ๋ณํ
โ ์ต๊ทผ ๋ํ + Context + ํ์ฌ ์ง๋ฌธ์ผ๋ก Prompt ์กฐ๋ฆฝ
โ Upstage LLM ํธ์ถ
โ ๊ฒ์ Metadata์์ Citation ์์ฑ
โ JSON ์๋ต๊ณผ Evidence ํ์
RAG(Retrieval-Augmented Generation)๋ LLM์ด ๋ต๋ณํ๊ธฐ ์ ์ ๊ด๋ จ ์๋ฃ๋ฅผ ๊ฒ์ํ๊ณ , ๊ฒ์ ๊ฒฐ๊ณผ๋ฅผ ์ง๋ฌธ๊ณผ ํจ๊ป ์ ๋ฌํด ๊ทผ๊ฑฐ ์๋ ๋ต๋ณ์ ์์ฑํ๊ฒ ํ๋ ํ์ดํ๋ผ์ธ์ ๋๋ค.
- Chunk: ๊ธด ์ฝ๋๋ ๋ฌธ์๋ฅผ ๊ฒ์ํ๊ธฐ ์ข์ ํฌ๊ธฐ๋ก ๋๋ ์กฐ๊ฐ
- Embedding: ์ฝ๋์ ์ง๋ฌธ์ ์๋ฏธ๋ฅผ ์ซ์ ๋ฒกํฐ๋ก ๋ณํํ๋ ๊ณผ์
- Chroma: ๋ฒกํฐ, ์๋ฌธ Chunk, ํ์ผ ๊ฒฝ๋ก์ ์ค ๋ฒํธ๋ฅผ ํจ๊ป ์ ์ฅํ๋ Vector DB
- Retrieval: ์ง๋ฌธ๊ณผ ์๋ฏธ๊ฐ ๊ฐ๊น์ด ์ฝ๋ Chunk ๊ฒ์
- Augmentation: ๊ฒ์ ๊ฒฐ๊ณผ๋ฅผ LLM์ด ์ฝ์ Context๋ก ์กฐ๋ฆฝ
- Generation: Context๋ฅผ ๊ทผ๊ฑฐ๋ก ๋ต๋ณ ์์ฑ
์ด ํ๋ก์ ํธ์ ๋ฐ์ดํฐ ํ๋ฆ์ ๋ค์๊ณผ ๊ฐ์ต๋๋ค.
GitHub URL โ ์ฝ๋ ์์ง โ Chunk โ Embedding โ Chroma
โ ๊ฒ์ โ Context โ Prompt โ LLM ๋ต๋ณ + Citation
RAG๋ ์๋ก์ด ๋ชจ๋ธ ํ๋๊ฐ ์๋๋ผ ๊ฒ์, Context ๊ตฌ์ฑ, Prompt ๊ตฌ์ฑ, ์์ฑ, ์ถ์ฒ ๋ฐํ์ ์ฐ๊ฒฐํ ์ฒ๋ฆฌ ๊ตฌ์กฐ์ ๋๋ค.
pirogramming-portfolio-rag-workshop/
โโโ config/ Django ํ๋ก์ ํธ ์ค์
โโโ portfolio/
โ โโโ management/commands/
โ โ โโโ ask_llm.py RAG ์๋ LLM ํธ์ถ ๋น๊ต
โ โ โโโ workshop_check.py API Key์ ์คํ ํ๊ฒฝ ์ ๊ฒ
โ โ โโโ mobile_serve.py ์ ํ ๊ธฐ๋ฅ: Tailscale ์ฐ๊ฒฐ
โ โโโ services/
โ โ โโโ conversation.py ๋ํ ์ํ์ ๊ฒ์ ์ฐ๊ฒฐ
โ โ โโโ rag.py Context, Prompt, Citation, ๋ต๋ณ
โ โ โโโ vector_store.py Chroma ์ ์ฅ๊ณผ ๊ฒ์
โ โ โโโ code_documents.py ์ฝ๋ Chunk์ ์ค Metadata
โ โ โโโ repository_url.py GitHub URL ๊ฒ์ฆ
โ โ โโโ source_policy.py ์์งํ ํ์ผ ์ ํ
โ โ โโโ github_client.py GitHub API ์์ฒญ๊ณผ ์ฌ์๋
โ โ โโโ jd_analyzer.py JD ์ฝ๋ ๊ทผ๊ฑฐ ๋ถ์
โ โโโ templates/portfolio/index.html ์ฑ๋ด ํ๋ฉด
โ โโโ static/portfolio/ CSS์ JavaScript
โ โโโ views.py HTTP ์์ฒญ๊ณผ JSON ์๋ต
โโโ fixtures/ GitHub ์ฅ์ ์ ์ํ ๋ฐ์ดํฐ
โโโ tests/ ๋จ๊ณ๋ณ ์๋ ํ
์คํธ
โโโ .env.example ํ๊ฒฝ๋ณ์ ์์
โโโ manage.py
โโโ pyproject.toml Python๊ณผ ํจํค์ง ์ค์
Starter์๋ ํจ์ ์ ์ธ, ํ์
ํํธ, import๊ฐ ์ด๋ฏธ ์์ต๋๋ค. ๊ฐ ๋์ ํจ์์ raise WorkshopStepIncomplete(...)๋ฅผ ์์ฑ ์ฝ๋๋ก ๊ต์ฒดํฉ๋๋ค.
| Step | ํ์ผ | ํจ์ | ํต์ฌ ๊ฐ๋ |
|---|---|---|---|
| 1 | portfolio/views.py |
messages |
๋ธ๋ผ์ฐ์ POST โ Form ๊ฒ์ฆ โ ์๋น์ค โ JSON |
| 2 | portfolio/services/conversation.py |
_answer_code_question |
์ง๋ฌธ โ Top 6 ๊ฒ์ โ RAG ๋ต๋ณ |
| 3 | portfolio/services/rag.py |
format_context |
๊ฒ์ Chunk โ LLM Context |
| 4 | portfolio/services/rag.py |
_answer_prompt |
์ต๊ทผ ๋ํ + Context + ์ง๋ฌธ |
| 5 | portfolio/services/rag.py |
_citations |
๊ฒ์ Metadata ๊ธฐ๋ฐ ์ถ์ฒ์ ์ค๋ณต ์ ๊ฑฐ |
| 6 | portfolio/services/rag.py |
answer_with_context |
๊ทผ๊ฑฐ ํ์ธ โ LLM ํธ์ถ โ ๋ต๋ณยท์ถ์ฒ ๋ฐํ |
๋ค์ ๋ก์ง์ ์์ฑ๋ ์ฝ๋๋ก ์ ๊ณต๋ฉ๋๋ค.
- GitHub URL ๊ฒ์ฆ:
parse_github_repository_url - ํ์ผ ์ ์ฑ
๊ณผ ์์ฐ:
select_source_candidates - ์ฝ๋ Chunk์ ์ค ๋ฒํธ:
chunk_source_file,build_code_documents - Chroma ๊ต์ฒด์ ๊ฒ์:
reset_and_index,search - JD ์ฝ๋ ๊ทผ๊ฑฐ ๋ถ์:
analyze_jd - GitHub ์ฌ์๋, ๋น๊ณต๊ฐ ์ ์ฅ์ ํ์ธ, ์์์ index ๊ต์ฒด, ํ๋ฉด ๋ ๋๋ง
- Python
3.11์ด์3.14๋ฏธ๋ง โ Python3.13๊ถ์ฅ - Git
- GitHub ๊ณ์ ๊ณผ Fine-grained personal access token
- Upstage API Key
- macOS, Linux ๋๋ Windows PowerShell
Python 3.14์์๋ ํ์ฌ ๊ณ ์ ๋ tokenizers๊ฐ ์ฌ์ฉํ๋ PyO3 ๋ฒ์ ์ด Python 3.13๊น์ง๋ง ์ง์ํด ์ค์น ๊ณผ์ ์์ wheel build๊ฐ ์คํจํฉ๋๋ค. Rust๋ฅผ ๋ค์ ์ค์นํ๊ธฐ๋ณด๋ค Python 3.13 ๊ฐ์ํ๊ฒฝ์ ์ฌ์ฉํ์ธ์.
์ฑ์ด ๋ถ์ ๋์ ์ ์ฅ์๋ฅผ ์ฝ์ ๋ ์ฌ์ฉํ๋ ์ธ์ฆ ๊ฐ์ ๋๋ค.
- GitHub Fine-grained token ์์ฑ ํ๋ฉด์ ์ฝ๋๋ค.
- ์์ ์ ํ์ํ ์งง์ ๋ง๋ฃ ๊ธฐ๊ฐ์ ์ค์ ํฉ๋๋ค.
- ๋น๊ณต๊ฐ ์ ์ฅ์๋ฅผ ์ฌ์ฉํ ๊ฒฝ์ฐ
Only select repositories๋ก ํ์ํ ์ ์ฅ์๋ง ์ ํํฉ๋๋ค. - Repository permissions์์
Contents: Read-only๋ฅผ ์ ํํฉ๋๋ค. - ์์ฑ ์งํ ๊ฐ์ ๋ณต์ฌํด
.env์GITHUB_TOKEN์๋ง ๋ฃ์ต๋๋ค.
์ฐ๊ธฐ ๊ถํ, Issues, Pull requests, Actions ๊ถํ์ ํ์ํ์ง ์์ต๋๋ค.
Chat ๋ชจ๋ธ๊ณผ Embedding ๋ชจ๋ธ์ ํธ์ถํ ๋ ์ฌ์ฉํ๋ ์ธ์ฆ ๊ฐ์ ๋๋ค.
- Upstage Console API Keys์ ๋ก๊ทธ์ธํฉ๋๋ค.
Create new key๋ฅผ ๋๋ฌ Key๋ฅผ ๋ฐ๊ธํฉ๋๋ค.- ๋ฐ๊ธ ์งํ ํ ๋ฒ๋ง ๋ณต์ฌํด
.env์UPSTAGE_API_KEY์ ๋ฃ์ต๋๋ค.
์ด ์ค์ต์ ํ๊ตญ์ด ์ฝ๋ ์ง๋ฌธ๊ณผ ์ค๋ช
์ ํ provider์์ ์ฒ๋ฆฌํ๊ณ , langchain-upstage๋ก Chat๊ณผ Embedding ์ฐ๊ฒฐ์ ๋จ์ํ๊ฒ ์ ์งํ๊ธฐ ์ํด Upstage๋ฅผ ์ฌ์ฉํฉ๋๋ค. ๊ณ์ credit๊ณผ rate limit์ด ์์ผ๋ฏ๋ก ์์
์ workshop_check๋ก ์ค์ ํธ์ถ ๊ฐ๋ฅ ์ฌ๋ถ๋ฅผ ํ์ธํด์ผ ํฉ๋๋ค.
์ ์ฅ์๋ฅผ ๋ด๋ ค๋ฐ์ต๋๋ค.
git clone https://github.com/inoaole/pirogramming-portfolio-rag-workshop.git
cd pirogramming-portfolio-rag-workshoppython3.13 -m venv .venv
source .venv/bin/activate
python -m pip install -e '.[dev]'
cp .env.example .envpython3.13 ๋ช
๋ น์ด ์๋ค๋ฉด ์ค์น๋ Python 3.11~3.13์ ๋ช
๋ น์ ์ฌ์ฉํฉ๋๋ค.
py -3.13 -m venv .venv
.venv\Scripts\Activate.ps1
python -m pip install -e ".[dev]"
Copy-Item .env.example .envPowerShell์ด ๊ฐ์ํ๊ฒฝ ์คํ์ ๋ง์ผ๋ฉด ์ฌ์ฉ์ ๊ณ์ ๋ฒ์์์ ํ ๋ฒ ์คํํฉ๋๋ค.
Set-ExecutionPolicy -Scope CurrentUser RemoteSigned.env ํ์ผ์ ๋ณธ์ธ์ด ๋ฐ๊ธํ ๊ฐ์ ์
๋ ฅํฉ๋๋ค.
GITHUB_TOKEN=๋ณธ์ธ์_fine_grained_token
USE_SAMPLE_GITHUB=false
UPSTAGE_API_KEY=๋ณธ์ธ์_upstage_api_key
UPSTAGE_CHAT_MODEL=solar-pro3
UPSTAGE_EMBEDDING_MODEL=solar-embedding-1-large
CHROMA_PATH=.workshop/chromaToken๊ณผ API Key๋ฅผ README, ๋ฉ์ ์ , ๋ธ๋ผ์ฐ์ ์
๋ ฅ์ฐฝ, ํ๋ฉด ์บก์ฒ ๋๋ Git commit์ ์ฌ๋ฆฌ์ง ์์ต๋๋ค. .env๋ Git์์ ์ ์ธ๋์ด ์์ต๋๋ค.
API ์์ด ๋ก์ปฌ ์ค์น๋ถํฐ ํ์ธํฉ๋๋ค.
python manage.py workshop_check --offline์ค์ Token๊ณผ Key๊น์ง ํ์ธํฉ๋๋ค.
python manage.py workshop_checkReady for workshop์ด ํ์๋๋ฉด ์ค๋น๊ฐ ๋๋ฌ์ต๋๋ค.
๊ฐ Step์์ ์ง์ ๋ ํจ์๋ง ์์ ํ๊ณ ํด๋น ํ
์คํธ๋ฅผ ํต๊ณผ์ํจ ๋ค ๋ค์ ๋จ๊ณ๋ก ์ด๋ํฉ๋๋ค. ์๋ ๋ช
๋ น์ ํ์ฑํ๋ ๊ฐ์ํ๊ฒฝ์ Python์ ์ฌ์ฉํ๋๋ก python -m pytest ํํ๋ก ์คํํฉ๋๋ค.
- ์์น:
portfolio/views.py์messagesํจ์ ์ ์ฒด - ์ญํ : ์ ๋ ฅ ๊ฒ์ฆ, session ์ ๋ฌ, ์๋น์ค ํธ์ถ, JSON ์๋ต
python -m pytest tests/test_step1_messages.py -q- ์์น:
portfolio/services/conversation.py์ConversationService._answer_code_question๋ฉ์๋ ์ ์ฒด - ์ฃผ์: ํด๋์ค ๋ด๋ถ ๋ฉ์๋์ด๋ฏ๋ก
def์์ 4์นธ์ ๋ค์ฌ์๋๋ค. - ์ญํ : Top 6 ๊ฒ์,
answer_with_contextํธ์ถ,ConversationReply๋ฐํ
python -m pytest tests/test_step2_conversation.py -q- ์์น:
portfolio/services/rag.py์format_contextํจ์ ์ ์ฒด - ์ญํ : repository, path, lines, URL, content๋ฅผ
<portfolio_context>๋ก ์กฐ๋ฆฝ
python -m pytest tests/test_step3_context.py -q- ์์น:
portfolio/services/rag.py์_answer_promptํจ์ ์ ์ฒด - ์ญํ : ์ต๊ทผ ๋ํ 6๊ฐ, ๊ฒ์ Context, ํ์ฌ ์ง๋ฌธ์ ์ผ์ ํ ์์๋ก ๊ฒฐํฉ
python -m pytest tests/test_step4_prompt.py -q- ์์น:
portfolio/services/rag.py์_citationsํจ์ ์ ์ฒด - ์ญํ : ๋น URL ์ ์ธ, ์ค๋ณต ์ ๊ฑฐ, relevance ๋ณด์กด
python -m pytest tests/test_step5_citations.py -q- ์์น:
portfolio/services/rag.py์answer_with_contextํจ์ ์ ์ฒด - ์ญํ : ๊ฒ์ ๊ฒฐ๊ณผ๊ฐ ์์ผ๋ฉด ๋ชจ๋ธ์ ํธ์ถํ์ง ์๊ณ , ์์ผ๋ฉด Upstage ๋ต๋ณ๊ณผ Citation์ ๋ฐํ
python -m pytest tests/test_step6_answer.py -q์ฒซ ๋ฒ์งธ ํฐ๋ฏธ๋์์ ์๋ฒ๋ฅผ ์คํํฉ๋๋ค.
python manage.py runserver 127.0.0.1:8000๋ธ๋ผ์ฐ์ ์์ http://127.0.0.1:8000์ ์ฝ๋๋ค.
https://github.com/owner/repositoryํ์์ ์ ํํ ์ ์ฅ์ URL์ ๋ณด๋ ๋๋ค.- ๋น๊ณต๊ฐ ์ ์ฅ์๋ผ๋ฉด Upstage ์ ์ก ์๋ด๋ฅผ ์ฝ๊ณ ๋์ ๋๋ ์ทจ์ํฉ๋๋ค.
- ์ธ๋ฑ์ฑ์ด ๋๋๋ฉด ์ฝ๋ ๊ตฌ์กฐ๋ ํจ์ ํธ์ถ ํ๋ฆ์ ์ง๋ฌธํฉ๋๋ค.
- Evidence์์ ํ์ผ ๊ฒฝ๋ก, ์ค ๋ฒ์, relevance์ GitHub ๋งํฌ๋ฅผ ํ์ธํฉ๋๋ค.
JD ์ ํฉ๋ ๋ถ์๊ธฐ๋ฅ์ ์์ฑ๋ ํ์ฅ ๊ธฐ๋ฅ์ผ๋ก ์คํํด ์ฝ๋ ๊ทผ๊ฑฐ๋ฅผ ํ์ธํฉ๋๋ค.
์ฌ์ฏ Step์ ๋ชจ๋ ์๋ฃํ ๋ค ์คํํฉ๋๋ค.
python -m pytest \
tests/test_step1_messages.py \
tests/test_step2_conversation.py \
tests/test_step3_context.py \
tests/test_step4_prompt.py \
tests/test_step5_citations.py \
tests/test_step6_answer.py -q
ruff check .
python manage.py checkGit clone์์ ์์ ํ๋ค๋ฉด ๋ค์๋ ํ์ธํฉ๋๋ค.
git diff --check
git status --short์ค๋ฅ์ configured Python interpreter version (3.14) is newer than PyO3's maximum supported version (3.13)๊ฐ ๋ณด์ด๋ฉด Python 3.14 ๊ฐ์ํ๊ฒฝ์
๋๋ค. .venv๋ฅผ ์ญ์ ํ๊ณ Python 3.13์ผ๋ก ๋ค์ ๋ง๋ญ๋๋ค.
์ค๋ฅ์ ํ์๋ Step ํจ์๊ฐ ์์ง ๋น์ด ์๋ค๋ ๋ป์ ๋๋ค. ํด๋น ํจ์์ body๋ง ์์ฑํ๊ณ ๊ทธ Step ํ ์คํธ๋ฅผ ๋ค์ ์คํํฉ๋๋ค. import, helper, test๋ฅผ ๊ณ ์ณ ์ฐํํ์ง ์์ต๋๋ค.
Fine-grained Token์ ๋ง๋ฃ ์ฌ๋ถ, repository ์ ํ, Contents: Read-only ๊ถํ์ ํ์ธํฉ๋๋ค.
.env์ UPSTAGE_API_KEY, UPSTAGE_CHAT_MODEL, UPSTAGE_EMBEDDING_MODEL ๊ฐ์ ํ์ธํ๊ณ python manage.py workshop_check๋ฅผ ๋ค์ ์คํํฉ๋๋ค.
๊ธฐ์กด Django ์๋ฒ๋ฅผ ์คํํ ํฐ๋ฏธ๋์์ Ctrl+C๋ฅผ ๋๋ฆ
๋๋ค.
macOS/Linux:
lsof -nP -iTCP:8000 -sTCP:LISTENWindows PowerShell:
Get-NetTCPConnection -LocalPort 8000 -State Listen -ErrorAction SilentlyContinue- GitHub Token๊ณผ Upstage API Key๋
.env์๋ง ์ ์ฅํ๊ณ ๊ณต์ ํ๊ฑฐ๋ commitํ์ง ์์ต๋๋ค. - ์ฑ์ GitHub ์ ์ฅ์์ ์ฐ์ง ์์ผ๋ฉฐ
Contents: Read-only๊ถํ๋ง ์ฌ์ฉํฉ๋๋ค. - ๋น๊ณต๊ฐ ์ ์ฅ์๋ ๋์ ํ ์ ํ๋ ์ฝ๋ Chunk๊ฐ Upstage Embedding ์์ฒญ์ผ๋ก ์ ์ก๋๊ณ , ๊ฒ์๋ Chunk๊ฐ Chat ์์ฒญ์ผ๋ก ์ ์ก๋ฉ๋๋ค.
- Chroma ์๋ฌธ๊ณผ ๋ฒกํฐ๋ ๋ก์ปฌ
.workshop/chroma/์ ์ ์ฅ๋ฉ๋๋ค. - ํ์ผ ํ์, ํฌ๊ธฐ, ์ ์ฒด ์ฉ๋, Chunk ๊ฐ์ ์ ํ ๋๋ฌธ์ ๋ชจ๋ ํ์ผ์ด ์ธ๋ฑ์ฑ๋๋ค๊ณ ๋ณด์ฅํ์ง ์์ต๋๋ค.
- RAG ๋ต๋ณ์ ๊ฒ์ ๊ฒฐ๊ณผ๋ฅผ ์์ฝํ ๊ฒ์ด๋ฏ๋ก ์ค์ํ ํ๋จ์ Evidence์ ์๋ณธ ํ์ผ๊ณผ ์ค ๋ฒํธ๋ก ํ์ธํฉ๋๋ค.
- JD ๊ฒฐ๊ณผ๋ ๊ณต๊ฐ ์ฝ๋์์ ํ์ธ๋๋ ๊ธฐ์ ๊ทผ๊ฑฐ ๋น์จ์ด๋ฉฐ ๊ฒฝ๋ ฅ, ํ์ ๋ฅ๋ ฅ ๋๋ ์ค์ ์ฑ์ฉ ๊ฒฐ๊ณผ๋ฅผ ์์ธกํ์ง ์์ต๋๋ค.