Spaces:
Sleeping
Sleeping
File size: 6,591 Bytes
9381502 56a2bc0 87b5875 | 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 | # ๊ฐ๋ฐ์ผ์ง: 2026-06-07
## ์ค๋์ ๋ชฉํ
์๊ฒฉ์ฆ ๋ฌธ์ ํ์ด ์น ํ๋ก์ ํธ๋ฅผ GitHub ํฌํธํด๋ฆฌ์ค์ฒ๋ผ ๊ธฐ๋กํ ์ ์๋๋ก README์ docs ๋ฌธ์๋ฅผ ์ ๋ฆฌํ๋ค.
๋จ์ํ ๊ธฐ๋ฅ ๋ชฉ๋ก๋ง ์ ๋ ๊ฒ์ด ์๋๋ผ, ์ ์ด ๊ตฌ์กฐ๋ฅผ ์ ํํ๋์ง์ ํ์ฌ ๊ฐ๋ฐ ์ค์ธ ์ํ๋ฅผ ์ด๋ณด์๋ ์ดํดํ ์ ์๊ฒ ์ค๋ช
ํ๋ ๊ฒ์ด ๋ชฉํ์๋ค.
## ์ค๋ ์ ๋ฆฌํ ๋ฌธ์
- `README.md`
- `docs/01_overview.md`
- `docs/02_architecture.md`
- `docs/03_data_pipeline.md`
- `docs/04_database.md`
- `docs/05_deployment.md`
- `docs/06_decision_log.md`
- `docs/07_troubleshooting.md`
- `docs/devlog/2026-06-07.md`
## ํ์ฌ ํ๋ก์ ํธ ์ดํด
์ด ํ๋ก์ ํธ๋ ์๊ฒฉ์ฆ ์ํ ๋ฌธ์ PDF๋ฅผ ์
๋ก๋ํ๊ณ , ๋ฌธ์ ๋ฅผ ๊ตฌ์กฐํํ ๋ค ์น์์ ํ ์ ์๊ฒ ๋ง๋๋ ์ฑ์ด๋ค.
ํ์ฌ ๊ตฌ์กฐ๋ Streamlit ์น ์ฑ์ ์ค์ฌ์ผ๋ก ๊ตฌ์ฑ๋์ด ์๋ค. ๋ฌธ์ ์ ํ์ด ๊ธฐ๋ก์ PostgreSQL์ ์ ์ฅํ๊ณ , ์ ์ฌ ๋ฌธ์ ๊ฒ์์ ์ํด Chroma๋ฅผ ์ฌ์ฉํ๋ค. PDF ์ฒ๋ฆฌ์ฒ๋ผ ์ค๋ ๊ฑธ๋ฆฌ๋ ์์
์ Airflow๋ก ๊ด๋ฆฌํ๋ ๋ฐฉํฅ์ด๋ค.
## ์ค๋ ํ์ธํ ์ค์ ์ฝ๋ ๊ตฌ์กฐ
ํ์ธํ ์ฃผ์ ํ์ผ:
- `streamlit_app.py`
- `cert_study_app/models.py`
- `cert_study_app/graphs/pdf_ingestion_graph.py`
- `cert_study_app/services`
- `dags/cert_study_pdf_ingestion_dag.py`
- `docker-compose.yml`
์ค์ ์ฑ์๋ ๋ฌธ์ ํ์ด, PDF ์
๋ก๋, ์ค๋ต/๋ณต์ต, ๊ฐ๋
์ ๋ฆฌ, ์ฒ๋ฆฌ ํํฉ, ์ํ ํํฉ, AI ์์ธ ํ๋ฆ์ด ์์๋ค.
๋ฐ์ดํฐ ๋ชจ๋ธ์๋ ๋ฌธ์ , ํ์ด ๊ธฐ๋ก, ๊ฐ๋
๋
ธํธ, PDF ์ฒ๋ฆฌ ์์
, ๋ฌธ์ ์์ธ ์์
์ด ์ ์๋์ด ์์๋ค.
## ์ค๋ ๋ฌธ์ํํ ํต์ฌ ๋ด์ฉ
### 1. ํ๋ก์ ํธ ๋ชฉ์
PDF ๋ฌธ์ ๋ฅผ ์ฌ๋์ด ์ง์ ์ ๋ฆฌํ๋ ๋ถ๋ด์ ์ค์ด๊ณ , ๋ฌธ์ ํ์ด์ ๋ณต์ต๊น์ง ์ด์ด์ง๋ ํ์ต ์น์ ๋ง๋๋ ๊ฒ์ด ๋ชฉ์ ์ด๋ค.
### 2. ์ ์ฒด ์ํคํ
์ฒ
Streamlit, PostgreSQL, Chroma, Airflow, Docker Compose๊ฐ ์ด๋ค ์ญํ ์ ํ๋์ง ์ ๋ฆฌํ๋ค.
`docs/02_architecture.md`์๋ Mermaid ๋ค์ด์ด๊ทธ๋จ๋ ์ถ๊ฐํ๋ค.
### 3. ๋ฐ์ดํฐ ํ์ดํ๋ผ์ธ
PDF ์
๋ก๋๋ถํฐ ๋ฌธ์ ์ ์ฅ๊น์ง์ ํ๋ฆ์ ๋จ๊ณ๋ณ๋ก ์ ๋ฆฌํ๋ค.
์ฃผ์ ํ๋ฆ:
1. PDF ์
๋ก๋
2. `IngestionJob` ์์ฑ
3. Airflow DAG ์คํ
4. PDF ํ์ฑ
5. ํ์ฑ ํ์ง ๊ฒ์ฆ
6. Quality Gate
7. PostgreSQL ์ ์ฅ
8. Chroma ์์ธ
### 4. PostgreSQL๊ณผ Chroma์ ์ญํ ๋ถ๋ฆฌ
PostgreSQL์ ์๋ณธ ๋ฌธ์ ์ ํ์ด ๊ธฐ๋ก์ ์ ํํ๊ฒ ์ ์ฅํ๋ ๊ธฐ์ค ์ ์ฅ์๋ก ์ค๋ช
ํ๋ค.
Chroma๋ ์ ์ฌ ๋ฌธ์ ๊ฒ์์ ์ํ ๋ณด์กฐ ์์ธ์ผ๋ก ์ค๋ช
ํ๋ค.
### 5. ๊ธฐ์ ์ ํ ์ด์
์์ฌ๊ฒฐ์ ๊ธฐ๋ก ๋ฌธ์์ ๋ค์ ๋ด์ฉ์ ADR ํํ๋ก ์ ๋ฆฌํ๋ค.
- Streamlit ์ ํ ์ด์
- PostgreSQL ์ ํ ์ด์
- Chroma ์ ํ ์ด์
- Airflow ์ ํ ์ด์
- Docker Compose ์ ํ ์ด์
- Oracle Cloud Ubuntu ๋ฐฐํฌ ๊ณํ
- ํ์ง ๊ฒ์ดํธ๋ฅผ ๋๋ ์ด์
## ํ์ฌ ๊ฐ๋ฐ ์ค์ธ ๋ถ๋ถ
์ด ํ๋ก์ ํธ๋ ์์ง ์์ฑ๋ ์ด์ ์๋น์ค๊ฐ ์๋๋ค. ๊ฐ์ธ ํ๋ก์ ํธ๋ก ๊ธฐ๋ฅ๊ณผ ๊ตฌ์กฐ๋ฅผ ๊ณ์ ๋ค๋ฌ๋ ์ค์ด๋ค.
ํ์ฌ ์ค์ํ๊ฒ ๋ณด๊ณ ์๋ ๊ฐ์ ์ :
- PDF ํ์ฑ ์ ํ๋ ๊ฐ์
- ๋ฌธ์ ์ฒญํน ํ์ง ๊ฒ์ฆ
- ํ์ง ๋ฆฌํฌํธ UI ๊ฐ์
- ๋ถ๋งํฌ ๊ธฐ๋ฅ
- ์ํ๋ณ ์ง๋์จ๊ณผ ์ ๋ต๋ฅ
- ์ค๋ณต ๋ฌธ์ ๊ฐ์ง
- Oracle Cloud Ubuntu ๋ฐฐํฌ
- ํ
์คํธ ์๋ํ
## ์ค๋์ ๊ฒฐ์
๋ฌธ์๋ ๊ณผ์ฅ๋ ์์ฑํ ์๋น์ค ์๊ฐ๊ฐ ์๋๋ผ, ํ์ฌ ๊ฐ๋ฐ ์ค์ธ ๊ฐ์ธ ํ๋ก์ ํธ๋ผ๋ ์ ์ ๋ถ๋ช
ํ ๋๋ฌ๋ด๋ ๋ฐฉํฅ์ผ๋ก ์์ฑํ๋ค.
๋ํ README๋ ์งง๊ฒ ์ ์ฒด๋ฅผ ์๊ฐํ๊ณ , ์์ธํ ๋ด์ฉ์ `docs/` ๋ฌธ์๋ก ์ฐ๊ฒฐํ๋ ๊ตฌ์กฐ๋ก ์ ๋ฆฌํ๋ค.
## ๋ค์ ์์
ํ๋ณด
- `.env.example` ์ ๊ฒ
- GitHub ์
๋ก๋ ์ ๋ถํ์ํ ๋ฐํ์ ํ์ผ ์ ์ธ ํ์ธ
- Oracle Cloud ๋ฐฐํฌ ์ ์ฐจ ์ค์ ๊ฒ์ฆ
- PDF ํ์ฑ ํ์ง ๋ฆฌํฌํธ ํ๋ฉด ๊ฐ์
- ๋ถ๋งํฌ ๊ธฐ๋ฅ ์ค๊ณ ๋ฐ ๊ตฌํ
- README์ ์คํฌ๋ฆฐ์ท ์ถ๊ฐ
## ์ถ๊ฐ ์งํ ๋ด์ฉ
GitHub์ Hugging Face Space ๋ฐฐํฌ ์๋ํ๋ฅผ ์ ๋ฆฌํ๋ค. Hugging Face์๋ ๋ก์ปฌ DB๋ PDF ์๋ณธ์ ์ง์ ์ฌ๋ฆฌ์ง ์๊ณ , ๋ฐฐํฌ์ฉ seed์ ํ์ํ ์ ์ ์ด๋ฏธ์ง๋ง ์ฌ๋ฆฌ๋ ๋ฐฉ์์ผ๋ก ๊ตฌ์ฑํ๋ค.
๋ฐฐํฌ์ฉ seed๋ `scripts/export_hf_seed.py`๋ก ์์ฑํ๋ค. ๊ธฐ์ค ๋ฌธ์ ๋ฐ์ดํฐ๋ `data/Json/questions.json`์ ์ฌ์ฉํ๊ณ , ๊ณตํต ์ง๋ฌธ๊ณผ ๊ณตํต ์ง๋ฌธ ์๋ฌธ ์ด๋ฏธ์ง๋ `data/parsed_json/reparsed_multipage_images_20260601_205501.json`์์ ๋ณด๊ฐํ๋ค.
ํ์ฌ ๋ฐฐํฌ์ฉ seed์๋ 321๋ฌธํญ์ด ๋ค์ด ์๋ค. ๊ณตํต ์ง๋ฌธ์ด ์๋ ๋ฌธํญ์ `parent_stem`๊ณผ `parent_image_paths`๋ฅผ ํจ๊ป ๊ฐ์ง๋ค.
๋ฌธ์ ํ์ด UI์์๋ Yes/No ์ง์ ํ ๋ฌธ์ ๋ฅผ ์ผ๋ฐ ๊ฐ๊ด์์ด ์๋๋ผ ์ง์ ๋ณ `์ / ์๋์ค` ๋งคํธ๋ฆญ์ค๋ก ํ์ํ๋๋ก ๊ฐ์ ํ๋ค. `1-A / 1-B / 2-A / 2-B`์ฒ๋ผ ํญ๋ชฉ๋ณ ์ ํ์ด ํ์ํ ๋ฌธ์ ๋ ํญ๋ชฉ๋ณ select๋ก ํ์ํ๋ค.
์ผ์๋ณ Git ๋ณ๊ฒฝ ํ์ธ์ ์ฝ๊ฒ ํ๊ธฐ ์ํด `scripts/git_daily_changes.sh`๋ฅผ ์ถ๊ฐํ๋ค.
```bash
scripts/git_daily_changes.sh 2026-06-07
```
## ๋ฌธ์ ์ ํ/๋ชจ๋ฐ์ผ UI ๊ฐ์
๋ฌธ์ ์ ํ์ด ์ฌ๋ฌ ํํ๋ก ๋ค์ด์ค๋ฉด์ ํ๋ฉด ํ์์ ์ฑ์ ๊ธฐ์ค์ด ์ด๊ธ๋ ์ ์๋ ๋ฌธ์ ๊ฐ ์์๋ค. ์๋ฅผ ๋ค์ด `Hotspot (True/False)`, `True/False (In-Context)`, `Hotspot (Drag and Drop)`์ฒ๋ผ ์๋ฌธ์์ ์จ ์ ํ๋ช
์ด ๋ด๋ถ ๋ก์ง๊ณผ ์ ํํ ๋ง์ง ์์ผ๋ฉด Yes/No ๋ฌธ์ ๊ฐ ๊ฐ๊ด์์ฒ๋ผ ๋ณด์ด๊ฑฐ๋, ์์๊ฐ ์ค์ํ ๋ต์์ด ์ผ๋ฐ ๋ณต์ ์ ํ์ฒ๋ผ ๋น๊ต๋ ์ ์์๋ค.
์ด๋ฅผ ์ค์ด๊ธฐ ์ํด ๋ค์ ๊ตฌ์กฐ๋ฅผ ์ถ๊ฐํ๋ค.
- `answer_normalizer.py`: Yes/No, ๊ฐ๊ด์, ๋ณต์ ์ ํ, ์์ํ ๋ต์์ ๋น๊ต ๊ฐ๋ฅํ ํํ๋ก ์ ๊ทํ
- `question_type_metadata_service.py`: ๋ค์ํ ๋ฌธ์ ์ ํ๋ช
์ ๋ด๋ถ ํ์ค ์ ํ์ผ๋ก ๋ณํ
- `tests/test_answer_normalizer.py`: ์ ๋ต ์ ๊ทํ ํ
์คํธ
- `tests/test_question_type_metadata_service.py`: ๋ฌธ์ ์ ํ alias ํ
์คํธ
๋ชจ๋ฐ์ผ ํ๋ฉด์ ๋ฌธ์ ํ์ด๋ฅผ ์ฒซ ๋ฒ์งธ ๋์ ์ผ๋ก ๋๊ณ , ์
๋ก๋/์ฒ๋ฆฌ ํํฉ/AI ์์ธ์ ๊ด๋ฆฌ ์์ญ์ผ๋ก ๋ฌถ์๋ค. ๋ต์ ์ ํ UI๋ ํฐ์นํ๊ธฐ ์ฝ๋๋ก ๋ฒํผ๊ณผ radio ์์ญ์ ๋์ด์ ๊ฐ๊ฒฉ์ ์กฐ์ ํ๋ค.
## ๋ฐฐํฌ/ํ์ง ๋ณด์
์ถ๊ฐ๋ก ๋ฐฐํฌ ์ ์ ๋์น๊ธฐ ์ฌ์ด ๋ถ๋ถ์ ์ ๋ฆฌํ๋ค.
- seed ๊ฐฑ์ ์ ์ฌ๋์ด ๊ฒ์ํ ๋ฌธ์ ๋ฅผ ๊ธฐ๋ณธ์ ์ผ๋ก ๋ฎ์ด์ฐ์ง ์๋๋ก ๋ณดํธ
- seed export ๊ฒฐ๊ณผ๋ฅผ `questions_seed.report.json`์ผ๋ก ์ ์ฅ
- `scripts/check_quality.py`๋ก ๋ฌธ๋ฒ ๊ฒ์ฌ์ ํต์ฌ ํ
์คํธ๋ฅผ ํ ๋ฒ์ ์คํ
- GitHub Actions `quality-check.yml` ์ถ๊ฐ
- `.env.example` ์ถ๊ฐ
- Docker Compose์์ ๋น๋ฐ๋ฒํธ์ ๋ชจ๋ธ ์ค์ ์ ํ๊ฒฝ ๋ณ์๋ก ๋ถ๋ฆฌ
- `CHANGELOG.md` ์ถ๊ฐ
|