Spaces:
Running
Running
File size: 14,169 Bytes
599b124 e516bd2 b84c523 e516bd2 599b124 9a65a94 599b124 9a65a94 599b124 | 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 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 | # Lab ์น์ธ GPX โ DemoService ๋ฐ์
## ์ด์ ๋ฐฐํฌ์ ๋ถ๋ถ ์ํ ํ์ธ
์ค์ Lab ์ค์น๋ณธ์ ๋ณดํธ ๊ธฐ๋ฅ์ ํฌํจํ ์ก์ ๊ธฐ๋ `tools/lab_sync/sync_lab_gpx.py`์
๋ณด์กดํ๋ค. ๊ธฐ์กด ์ํ ํ์ผยท์ ๊ธ ํ์ผ์ ๊ทธ๋๋ก ์ฌ์ฉํ๋ฉฐ v2๋ ๋ช
์์ ์ผ๋ก ์ ํํ๋ค.
Hugging Face ์์ ์คํฌ๋ฆฝํธ๋ ์๋น์ค ์์ ์ ์ ์๋ฒ ์์์ migrationยท์์ ยท์นดํ๋ก๊ทธ์
์ค์ PostgreSQL DB์ ์คํค๋งยทํ
์ด๋ธ ์๋ณ์๊ฐ ์ผ์นํ๋์ง ๊ฒ์ฌํ๋ค. ๋ค๋ฅด๋ฉด migration์
์คํํ์ง ์๋๋ค. ๋์ผํจ์ ํ์ธํ ๋ค migration 0014๋ฅผ ์ ์ฉํ๊ณ ๊ธฐ์กด ํ ์ ๋ณด์กด์
๊ฒ์ฌํ๋ค. ์ ์ ๋ฌธ์์ด๊ณผ ์๋ณธ ์๋ฃ๋ ์ถ๋ ฅํ์ง ์๋๋ค.
๊ฐ์ ์์ ์ธ์ฆ์ ์๊ตฌํ๋ `GET /deployment-status`๋ ๋ฐฐํฌ GitHub SHA, ์ค์ migration
revision, ์ธ ํ์ ์กด์ฌ ๋ฐ ์๋ฒ์ ๋์ผ DB ์ฌ์ ๊ฒ์ฌ ๊ฒฐ๊ณผ๋ง ๋ฐํํ๋ค.
`GET /routes/{source_id}/storage`๋ ์ ์ฅ๋ ์ธ ํ๋ฅผ ์๋ฒ์ ์ฝ๊ธฐ ์ ์ฉ ํธ๋์ญ์
์ผ๋ก ์กฐํํ์ฌ
์ค์ ๋ art IDยท๋ด์ฉ ํด์ยทํ์ฑ ์ํ์ GPX/์ ์ฅ ์ขํ ์ผ์น ์ฌ๋ถ๋ฅผ ๋ฐํํ๋ค.
์๋ณธ GPXยท์ขํยท๋์ ๋ณธ๋ฌธ์ด๋ DB ์ ์์ ๋ณด๋ ์๋ต์ ํฌํจํ์ง ์๋๋ค.
`GET /inventory`๋ ๊ฐ์ ์ถ์ฒ์ ์ ์ฒด ๋ผ์ด๋ธ๋ฌ๋ฆฌ ID์ ์ค์ art ์ฐ๊ฒฐยทํ์ฑ ์ํยท๋ด์ฉ
ํด์๋ง ๋ฐํํ๋ค. ์ ์ฒด ๋๊ธฐํ๋ ์ด๋ฅผ ์น์ธ ๋ชฉ๋ก๊ณผ ๋์กฐํ์ฌ ์ด๋ฏธ ํ์ธ๋ ์๋ฃ์ PUT์
์๋ตํ๊ณ ์ค์ ๋นํ์ฑํ ๋์์ ์ฐ์ถํ๋ค. v2 ์น์ธ ์ค๋
์ท์ ์ ํ์
`expected_catalog_revision`, `expected_deactivation_ids`๋ฅผ ํจ๊ป ์ฌ์ฉํ๋ฉด ์๋ฒ๋ ๊ฐ์
์ถ์ฒ ์ ๊ธ ์๋ ๊ฐ์ ๋ฒํธ์ ์ทจ์ ๋์์ด ์์๊ณผ ์ผ์นํ ๋๋ง ๋นํ์ฑํ๋ฅผ ์ ์ฉํ๋ค.
์๋ณธ GPXยท์ขํ๋ ๋ชฉ๋ก ์๋ต์ ํฌํจํ์ง ์๋๋ค.
์ค์ ํ ๊ฑด ์ํ์ ํ์ฌ accepted ์๋ฃ์ `--probe-id`๋ก ๋ถ๋ถ ์ธ์
์ ์ฌ์ฉํ๋ค.
์ ์ฅ ์๋ต์ ํ์ธํ ๋ค storage ์กฐํ์ ์ค์ ID์ ๋น๊ตํ๋ค. ์ ์ฒด ์น์ธ ์ค๋
์ท์
๋ณด๋ด์ง ์๊ณ ๋ฐ๋ณต ์คํ์ด๋ ๋๋ ์ ์ก์ ์๋์ผ๋ก ์์ํ์ง ์๋๋ค.
## v2: ๋์ยท๋ผ์ด๋ธ๋ฌ๋ฆฌยท๊ฒฝ๋ก ํ๋ณด๋ฅผ ํจ๊ป ์ ์ฅ
`--contract-version 2`๋ Lab์์ HTTP API๋ง ์ฌ์ฉํ๋ค. Lab์ ์ฝ๊ธฐ ์ ์ฉ
SQLite ์น์ธ ์กฐํ์ ๋ณ๋์ ๋ก์ปฌ ์ ์ก ์ํ SQLite ์ธ์๋ DB์ ์ ์ํ์ง ์๋๋ค.
DemoService PostgreSQL ๋๋ผ์ด๋ฒยท์ ์ ๋ฌธ์์ด์ Lab์ ํ์ํ์ง ์๋ค.
๊ธฐ์กด CLI์ ์์ฒญ์ ๊ธฐ๋ณธ์ ์ผ๋ก v1์ ์ ์งํ๋ฉฐ, v2 ์ ํ์ ๋ช
์์ ์ผ๋ก ์ํํ๋ค.
์๋ฒ๋ ๊ธฐ์กด ์ธ์ฆยท์๋ฒ DB ์ค์ ์ผ๋ก ๋ค์์ **๊ฒฝ๋ก 1๊ฑด๋น ํ ํธ๋์ญ์
**์์ ์ ์ฅํ๋ค.
1. ์๋ณธ DesignSpec digest๋ฅผ ๊ฒ์ฆํ๊ณ `art_templates`๋ฅผ ํ์ธยท๋ฑ๋กํ๋ค.
2. `lab_route_library`์ GPX์ ์์น ์๋ XY ์ธ๊ณฝ์ ์ ์ ์ฅํ๋ค.
3. GPX์์ ์ง์ ํ์ฑํ WGS84 `[์๋, ๊ฒฝ๋]`๋ง `art_route_candidates.coordinates`์ ์ ์ฅํ๋ค.
๋์ SVG๋ ์๋ณธ ๋์ ์ ๋ค๋ก ์์ฑํ๋ค. HTTP ์์ฒญ์ ์๋ ๊ฒฝ๋กยทํ์ผ๋ช
์ ์๋ฒ์์
์ด์ง ์๋๋ค. v2๋ ํด๋ผ์ด์ธํธ๊ฐ ์ง์ ์ง์ ํ๋ ํ๋ณด GPS ๋ฐฐ์ด๊ณผ SVG ๋ณธ๋ฌธ์ ๋ฐ์ง ์๋๋ค.
๋์ ์์ฒด์ `design_ai_status`์ ๊ฒฝ๋ก์ AIยท๋๋ก ๊ฒ์ฆ์ ๋ณ๋๋ก ์ ์ฅํ๋ค.
`ai_reject` ๋์๋ ์น์ธ ๊ฒฝ๋ก์ ์๋ณธ ์ฐธ์กฐ๋ก ๋ณด์กดํ ์ ์์ง๋ง ์น์ธ ๋์์ผ๋ก ์น๊ฒฉํ์ง ์๋๋ค.
`ai_pass` ๋์์ ์ฃผ์ฅํ๋ ค๋ฉด ํด๋น ๋์ ์์ฒด์ ๋ ๋ชจ๋ธ ๊ฒ์ ๊ทผ๊ฑฐ๋ ํ์ํ๋ค.
### v2 ์์ฒญ ํ๋
๊ธฐ์กด GPXยท๋ผ๋ฒจยท์ง์ญยท์น์ธ ์๊ฐยท๊ฒ์ ์ ์ฑ
ํ๋์ ๋ค์์ ์ถ๊ฐํ๋ค.
| ํ๋ | ์๋ฏธ |
|---|---|
| `contract_version` | `2` |
| `session_id`, `generation` | ์๋ฒ๊ฐ ๋ฐ๊ธํ ํ์ฌ ์ถ์ฒ ์ธ์
ยท์ธ๋ |
| `payload_sha256` | ์๋ ๊ท์น์ผ๋ก ๊ณ์ฐํ ์๋ฏธ์ ๋ด์ฉ ํด์ |
| `template.design_id`, `source_version`, `design_digest` | ์๋ณธ ๋์ ์๋ณ |
| `template.snapshot` | digest ๊ฒ์ฆ์ ์ฌ์ฉํ ์๋ณธ DesignSpec ์ ์ฒด JSON |
| `template.design_ai_status`, `design_ai_evidence` | ์๋ณธ ๋์์ ๋
๋ฆฝ AI ํ์ |
| `route_ai_evidence` | ๊ฒฝ๋ก์ ์ค์ ๋ ๋ชจ๋ธ ๊ฒ์ ๊ทผ๊ฑฐ |
| `road_verification`, `graph_sha256` | ์ ์ฅ๋ ๋๋ก ๊ฒ์ฌ์ ๊ทธ๋ํ ๋ฒ์ ๊ทผ๊ฑฐ |
| `distance_m`, `validator_version` | ์๋ณธ ๋๋ก ๊ธธ์ด์ ์ ์ ๋ฏธํฐ์ ๊ฒ์ฆ ์ ์ฑ
๋ฒ์ |
| `previous_payload_sha256` | ๋ช
์์ ๊ฐฑ์ ์ ๋น๊ตยท๊ตํ ์กฐ๊ฑด. ๊ธฐ๋ณธ๊ฐ ์์ |
| `reapprove` | ์ทจ์ ํ ๋ช
์์ ์ฌ์น์ธ. ๊ธฐ๋ณธ๊ฐ false |
๋ด์ฉ ํด์๋ ํค ์ ๋ ฌ, UTF-8, `ensure_ascii=False`, `allow_nan=False`,
๊ตฌ๋ถ์ `,`ยท`:`์ธ JSON์ SHA-256์ด๋ค. `session_id`, `generation`,
`payload_sha256`, `gpx_base64`, `previous_payload_sha256`, `reapprove`๋ ์ ์ธํ๋ค.
GPX ๋ฐ์ดํธ๋ ๋ณธ๋ฌธ ๋์ ๊ฒ์ฆ๋ `sha256` ํ๋๋ก ํด์์ ์ฐ๊ฒฐ๋๋ค.
๋๋จธ์ง ๊ธฐ๋ณธ ํ๋๋ ์๋ตํ์ง ์๊ณ ์ก์ ๊ธฐ์ ์๋ฒ ๋ชจ๋ธ์ ๊ฐ์ด ์ผ์นํด์ผ ํ๋ค.
### ์ธ์
๊ณผ ์น์ธ ์ทจ์
- `GET /sync-state`: ๊ณ์ฝ ๋ฒ์ ยทํ์ฌ ์ธ๋ยท์นดํ๋ก๊ทธ ๊ฐ์ ๋ฒํธ๋ง ๋ฐํํ๋ค.
- `POST /sync-sessions`: `client_request_id`, `expected_generation`, `mode`,
์๋ณธ ๊ฒฝ๋ก ID โ ๋ด์ฉ ํด์์ธ `manifest`, `manifest_sha256`์ผ๋ก ์์ํ๋ค.
- `PUT /routes/{source_id}`: ์ธ์
manifest์ ๋ด์ฉ ํด์๊ฐ ์ผ์นํ๋ ์๋ฃ๋ง ์ ์ฅํ๋ค.
- `GET /sync-sessions/{session_id}`: ํ์ฌ ์ธ์
์ ์ ์ฅ ์ํ๋ฅผ ์กฐํํ๋ค.
- `POST /sync-sessions/{session_id}/complete?generation=...`: ๋ถ๋ถ ์ ์ก์ ์๋ฃํ๋ค.
๋ค๋ฅธ ์๋ฃ๋ฅผ ๋นํ์ฑํํ์ง ์๋๋ค.
- ๊ธฐ์กด `POST /approval-snapshot`: v2์์๋ `session_id`, `generation`,
`manifest_sha256`๋ ๋ฐ๋๋ค. ์ ์ฒด ์ธ์
์ ๋ชจ๋ art ์ฐ๊ฒฐ์ด ํ์ธ๋ ๊ฒฝ์ฐ์๋ง
๋ผ์ด๋ธ๋ฌ๋ฆฌ์ ํ๋ณด ๊ฒฝ๋ก๋ฅผ ํจ๊ป ๋นํ์ฑํํ๋ค.
์ ์ธ์
์ ์ด์ ์ธ์
์ ์ฐจ๋จํ๋ค. ์ธ์
์์ ์์ฒญ์ ๋ก์ปฌ ์ํ์ ๋จผ์ ์ ์ฅํ
`client_request_id`๋ก ์ฌ์๋ํ๋ฉฐ, ์๋ต ์ ์ค ๋๋ฌธ์ ์ธ๋๋ฅผ ์๋ก ๋ฐ๊ธํ์ง ์๋๋ค.
์ด๋ฏธ ์๋ฃ๋ ๋์ผ ์ค๋
์ท์ ์ฌ์๋๋ ๊ฐ์ ๊ฒฐ๊ณผ๋ฅผ ๋ฐํํ๋ค.
๊ธฐ์กด์ ๋๋ ๋นํ์ฑํ ๋ฐฉ์ง ์ ํ์ ์ ์งํ๋ฉฐ, ๋ถ๋ถ ๋ชฉ๋ก์ ์ ์ฒด ๋ชฉ๋ก์ผ๋ก ๋ณด๋ด๋ฉด ์ ๋๋ค.
### ๋ฉฑ๋ฑ ์ ์ฅ๊ณผ ๋ช
์์ ๋ณ๊ฒฝ
๊ฐ์ IDยท๊ฐ์ ๋ด์ฉ์ `result=unchanged`๋ก ์ค์ ์ ์ฅ UUID๋ฅผ ๋๋ ค์ฃผ๊ณ ,
์
๋ฌด ํ์ `updated_at`๋ ๊ฐฑ์ ํ์ง ์๋๋ค. ๋ค๋ฅธ ๋ด์ฉ์ ๊ธฐ๋ณธ์ ์ผ๋ก 409๋ค.
`--allow-updates`๋ ๋ก์ปฌ์ ๋ณด์กด๋ ์ง์ ์ ์ฅ ์๋ต์ ํด์๋ก ๋น๊ตยท๊ตํ์ ์์ฒญํ๋ค.
๋ก์ปฌ ์ด๋ ฅ์ด ์์ผ๋ฉด ์ด ์ต์
๋ง์ผ๋ก ์์์ ์๋ฒ ๋ด์ฉ์ ๋ฎ์ด์ธ ์ ์๋ค.
์ทจ์๋ ๊ฒฝ๋ก๋ `--allow-reapproval`๊ณผ ์ด์ ๋ณด๋ค ๋ฆ์ ์๋ณธ ์น์ธ ์๊ฐ์ด ํ์ํ๋ค.
v2๋ก ์ ์ฅ๋ ๋ด์ฉ๋ ๋ฌ๋ผ์ก๋ค๋ฉด ์ง์ ๋ด์ฉ ํด์ ์กฐ๊ฑด์ ํจ๊ป ๋ง์กฑํด์ผ ํ๋ค.
์ค๋๋ ์ธ์
์ ์ด ์ต์
๋ค๊ณผ ๊ด๊ณ์์ด ๊ฑฐ์ ํ๋ค.
์ฑ๊ณต ์๋ต์ ์ปค๋ฐ ํ์ `art_template_id`, `art_route_candidate_id`,
`design_ai_status`, `route_validation_status`, `payload_sha256`, `contract_version`์
ํฌํจํ๋ค. ์ก์ ๊ธฐ๋ ์ด ์๋ต์ ํ์ธํ ๋ค์๋ง `http_v2_sent`์ ์๋ฃ ๊ธฐ๋ก์ ๋จ๊ธด๋ค.
์ `sent` ํ
์ด๋ธ์ ๊ธฐ๋ก์ v2 ์ ์ฅ ์ฑ๊ณต์ผ๋ก ๊ฐ์ฃผํ์ง ์๋๋ค.
์ค๋จ๋ ๊ฐ์ ์ธ์
์ ํ์ธ๋ ์์ฒญ๋ถํฐ ์ด์ด์ ์ฒ๋ฆฌํ๋ค. ์ ์ธ์
์์๋ ๊ธฐ์กด ์๋ฃ๋
HTTP ๋ฉฑ๋ฑ ์ ์ฅ์ผ๋ก ๋ค์ ํ์ธํ๋ฏ๋ก ๋ฐ๋ณต ์คํ ๊ฐ๊ฒฉ์ ์ด์ ๊ท๋ชจ์ ๋ง์ถฐ ์ ํด์ผ ํ๋ค.
### ํธํ์ฑ๊ณผ ์ฌ์ ์กฐ๊ฑด
๊ธฐ์กด v1 ์์ฒญยท์๋ต ํ์์ ์ ์งํ๋ค. ๋ค๋ง ํ ์ถ์ฒ๊ฐ v2 ๊ด๋ฆฌ๋ก ์ ํ๋ ๋ค์๋
v1์ ๋์ผ ํ์ฑ ์๋ฃ ํ์ธ๋ง ํ์ฉํ๊ณ , ์ ์ฐ๊ธฐยท๊ฐฑ์ ยท์ค๋
์ท์ 409๋ก ์ฐจ๋จํ๋ค.
v1 ์์ฒญ์๋ ์ธ๋ยท์๋ณธ ๋์ ์ ๋ณด๊ฐ ์์ผ๋ฏ๋ก ๊ฐํ ์์ ๋ณด์ฅ์ด๋ art ์ ์ฅ ์ฑ๊ณต์
๋์ ์ฃผ์ฅํ์ง ์๋๋ค. v1์์๋ ์ทจ์๋ ๊ฒฝ๋ก๋ฅผ ์ฌ์ ์ก๋ง์ผ๋ก ์ฌํ์ฑํํ์ง ์๋๋ค.
์ด์์์๋ ์ธ ์
๋ฌด ํ
์ด๋ธ์ด ๊ฐ์ ์๋ฒ DB์ ์กด์ฌํ๊ณ migration 0014๊ฐ ์ ์ฉ๋์ด์ผ ํ๋ค.
์์ฒญ ์ค์๋ ํ
์ด๋ธ์ ์์ฑํ์ง ์๋๋ค. ๊ฐ์ ๋์ ๋ถ๋ฅ์ ๋ด๋ถ ์ ์ ๋ฒ์ ์ ์๋ฒ๊ฐ
์ ๊ธ ์๋ ๋ฐฐ์ ํ๊ณ , ์๋ณธ IDยท๋ฒ์ ยทdigest์ ๋ณ๋๋ก ๋ณด์กดํ๋ค.
์ด์ Alembic ์ด๋ ฅ์ `routes`ยท`run_sessions` ๊ธฐ์ด ํ
์ด๋ธ์ ์กด์ฌ๋ฅผ ์ ์ ๋ก ํ๋ค.
๋ฒ์ ๋ฌธ์์ด์ด 32์๋ฅผ ๋์ผ๋ฏ๋ก ๋ฒ์ ํ
์ด๋ธ์ 128์๋ฅผ ์ฌ์ฉํ๋ฉฐ ๊ธฐ์กด ์งง์ ์ปฌ๋ผ์
๋ง์ด๊ทธ๋ ์ด์
์คํ ์ ๋ฐ์ดํฐ ๋ณด์กด ๋ฐฉ์์ผ๋ก ๋ํ๋ค.
์๋๋ ํฅํ ๊ฒ์ฆ ํ๊ฒฝ์์ ์ฌ์ฉํ ํํ์ด๋ฉฐ, ์ค์ ์น์ธ ์๋ฃ๋ก ์คํํ ๋ช
๋ น์ด ์๋๋ค.
```bash
python tools/sync_lab_gpx.py \
--root /path/to/synthetic-lab \
--url https://example.invalid/api/v1/ai/internal/route-library \
--token-file /path/to/existing-auth-file \
--contract-version 2 --check-only
```
`--check-only`๋ ์ธ์ฆ ํ์ผ์ ์ฝ๊ฑฐ๋ HTTP ์์ฒญ์ ๋ณด๋ด์ง ์๋๋ค.
์ค์ ์ํ ์ ์ก์ ๋ณ๋ ํ์ฉ ํ `--probe-id` ๋๋ `--max-routes`๋ก ๋ฒ์๋ฅผ ์ ํํ๋ค.
์ด ๋ ์ต์
์ ๋ถ๋ถ ์ธ์
์ ์ฌ์ฉํ์ฌ ์น์ธ ์ทจ์๋ฅผ ๋ณด๋ด์ง ์๋๋ค.
`--new-session`์ ์ค๋๋ ๋ฏธ์๋ฃ ์ธ์
๋์ ํ์ฌ ์น์ธ ์๋ฃ๋ก ์ ์ธ์
์ ์์ํ๋
๋ช
์์ ๋ณต๊ตฌ ์ต์
์ด๋ค. ๋์ ์ก์ ๊ธฐ๋ ์ํ ํ์ผ๋ณ ์ ๊ธ์ผ๋ก ์ฐจ๋จํ๋ค.
์ด ์ ์ฅ์์ ๋ณ๊ฒฝ์ ๊ธฐ์กด Lab ์คํ ํ์ผ์ ์๋์ผ๋ก ๊ต์ฒดํ์ง ์๋๋ค.
๊ฐํ ์ก์ ๊ธฐ๋ฅผ ๊ต์ฒดํ ๋๋ ๊ธฐ์กด ์ํ ํ์ผยท์น์ธ ๊ฐ๋ยท์ด์ ์ ํ์ ๋ณด์กดํ๊ณ ,
๊ธฐ์กด ํ๋ก์ธ์ค์์ ๋์ ์คํ์ ๋ง๋ ์ ํ ์ ์ฐจ๋ฅผ ๋ณ๋๋ก ํ์ธํด์ผ ํ๋ค.
## ๊ธฐ์กด v1 ์ฐ๋
Lab ์ ๊ตญ ์์ง๊ธฐ์ `accepted JOIN items`์ ์๋ ์น์ธ ๊ฒฝ๋ก๋ง ๋๊ธฐํํ๋ค. Lab์
`inventory.sqlite3`์ router ์ผ๋ฐ Worker์ `routes.sqlite3`๋ ์๋ก ๋ค๋ฅธ
์๋ฃ๋ค. `tools/sync_lab_gpx.py`๋ ์ ์๋ฅผ ์ฝ๊ณ , DemoService์ AI ์๋น์ค๊ฐ
์๋ณธ GPX์ ์์น๋ฅผ ์ ๊ฑฐํ ์ค๊ณฝ์ ์ธ๋ถ PostgreSQL์ ์ ์ฅํ๋ค. ๊ฒฝ๋ก ์์ฑ์
DB์ ํ์ฑ ์ค๊ณฝ์ ๊ธฐ์กด ํ์ผ ๋์๊ณผ ํฉ์ณ ์ฌ์ฉํ๋ค.
## ์์ ์๋ฒ ์ค๋น
1. Lab์์ ๊ธด ์์ ํ ํฐ์ ์์ฑํด `/home/jovyan/.config/demoservice-sync/token`์
๋ณด๊ดํ๊ณ , ๊ฐ์ ๊ฐ์ GitHub ์ ์ฅ์์ Actions Secret `ROUTE_LIBRARY_TOKEN`์
๋ฑ๋กํ๋ค. ๋ฐฐํฌ ์ํฌํ๋ก๊ฐ ์ด ๊ฐ์ Hugging Face Space Secret์ ๋๊ธฐํํ๋ค.
๊ฐ์ด ์์ผ๋ฉด ์์ API๋ `503`์ผ๋ก ๋นํ์ฑํ๋๋ค. ํ ํฐ ๊ฐ์ ๋ก๊ทธ๋ ์ฑํ
์
๊ธฐ๋กํ์ง ์๋๋ค.
2. AI ์๋น์ค์ `ROUTE_LIBRARY_DATABASE_URL`์ ์๊ตฌ PostgreSQL ์ฐ๊ฒฐ ๋ฌธ์์ด๋ก
์ค์ ํ๋ค. Hugging Face ์์ ์คํฌ๋ฆฝํธ๋ ๋ฏธ์ค์ ์ ๊ธฐ์กด `DATABASE_URL`์
์ฌ์ฉํ๋ค. DB ๊ณ์ ์๋ `lab_route_library` ํ
์ด๋ธ ์์ฑยท์กฐํยท์์ ๊ถํ์ด
ํ์ํ๋ค. ๋ก์ปฌ Docker Compose๋ `AUTH_DATABASE_URL`์ ์ ๋ฌํ๋ค.
3. DemoService ์ฝ๋๋ฅผ ๋ฐฐํฌํ๊ฑฐ๋ ๋ฐฐํฌ ์ํฌํ๋ก๋ฅผ ๋ค์ ์คํํ๋ค. Lab ์ ์ก์
์ํฌํ๋ก๊ฐ Secret ๋ฐ์๊ณผ Space ๋๊ธฐํ์ ์ฑ๊ณตํ ๋ค ์์ํ๋ค.
์์ ๊ฒฝ๋ก๋ Gateway๋ฅผ ํต๊ณผํ๋
`/api/v1/ai/internal/route-library/routes/{source_id}` (`PUT`)์ด๋ค.
`Authorization: Bearer <ROUTE_LIBRARY_TOKEN>`๊ณผ JSON ๋ณธ๋ฌธ์ ๋ค์ ํ๋๋ฅผ ๋ณด๋ธ๋ค.
```json
{
"label": "dog", "region_code": "expanded_gunsan", "region_name": "๊ตฐ์ฐ ์์ก",
"sha256": "<GPX ํ์ผ SHA-256>", "accepted_at": "2026-11-08T08:47:31+00:00",
"review_status": "ai_pass", "ai_protocol": "national-blind-upright-v5-outline-and-silhouette",
"geometry_ok": true, "seoul_ok": true, "collection_finalized": false,
"gpx_base64": "<๊ฐ๋ณ GPX ํ์ผ์ Base64>"
}
```
ID๋ Lab์ 64์๋ฆฌ SHA-256 ํ์ ์๋ณ์๋ค. ์์ ์ธก์ ๋ผ๋ฒจ 7๊ฐ,
GPX SHA-256, ํ์ผ ํฌ๊ธฐ(์ต๋ 128 KiB), ๋จ์ผ ํธ๋ยท๊ตฌ๊ฐ, ์ขํ์ ๋ซํ ๊ฒฝ๋ก๋ฅผ
๊ฒ์ฆํ๋ค. ๊ฐ์ ID์ ์ฌ์ ์ก์ ๊ฐฑ์ ์ฒ๋ฆฌํ๋ฉฐ ๋ผ๋ฒจ์ DemoService ๋ด๋ถ ์ฝ๋๋ก
๋ณํํ๋ค: `tree โ christmas_tree_trunk`, `tshirt โ t_shirt`,
`pants โ long_pants`, `star โ symbol_star`.
์ ์ฒด ์น์ธ ๋ชฉ๋ก์ ๋๊ธฐํํ ๋ค
`POST /api/v1/ai/internal/route-library/approval-snapshot`์ผ๋ก `ids`,
`count`, `ids_sha256`, `collection_finalized`๋ฅผ ๋ณด๋ธ๋ค. `ids_sha256`์ ID๋ฅผ
์ฌ์ ์ ์ ๋ ฌํด ์ค๋ฐ๊ฟ์ผ๋ก ์ฐ๊ฒฐํ UTF-8 ๋ฌธ์์ด์ SHA-256์ด๋ค. ์ ์ก๋์ง
์์ ID๊ฐ ๋ชฉ๋ก์ ์์ผ๋ฉด ๊ฑฐ์ ํ๋ค. ๋ชฉ๋ก์์ ์ ์ธ๋ ID๋ ๋นํ์ฑํํ๋ฉฐ,
ํ ๋ฒ์ ๊ธฐ์กด ํ์ฑ ๋ฐ์ดํฐ์ 5% ๋๋ 20๊ฐ ์ค ํฐ ๊ฐ๋ณด๋ค ๋ง์ด ์ ์ธ๋๋ฉด
์ค๋ฅ๋ก ์ค๋จํ๋ค. ์ด ์ ํ์ ์๋ชป๋ ๋ถ๋ถ ๋ชฉ๋ก์ ๋๋ ๋นํ์ฑํ๋ฅผ ๋ง๋๋ค.
## Lab ์ ์ก
์ ๊ณต์๋ฒ์์ ์ ์ฅ์์ `tools/sync_lab_gpx.py`๋ฅผ ์คํํ๋ค. ํ์ผ์ Lab ์ชฝ
`accepted JOIN items`๋ฅผ ์ฝ์ผ๋ฉฐ `ai_pass`, `geometry_ok`, `seoul_ok`๋ฅผ
์ฌ๊ฒ์ฌํ๋ค. ํ ํฐ์ ํ์ผ์์ ์ฝ๊ณ ๋ก๊ทธ์ ์ถ๋ ฅํ์ง ์๋๋ค.
```bash
python tools/sync_lab_gpx.py \
--root /home/jovyan/artifacts/national-ai-seven-100-20261106 \
--url https://tkadkghdlf-cd.hf.space/api/v1/ai/internal/route-library \
--token-file /home/jovyan/.config/demoservice-sync/token
```
์ ๊ธฐ๋ณธ ๋ช
๋ น์ ์น์ธ ๋ชฉ๋ก ์ ์ฒด๋ฅผ ์ ์กํ๋ค. ์ฒซ ์ํ์๋ ์ ๋ช
๋ น์
`--probe-id <accepted์ ์๋ GPX ID>`๋ฅผ ์ถ๊ฐํ๋ค. ์ด ์ต์
์ ํด๋น GPX
ํ ๊ฑด๋ง ๋ณด๋ด๋ฉฐ ์น์ธ ๋ชฉ๋ก ์ค๋
์ท๊ณผ ๋นํ์ฑํ ์์ฒญ์ ๋ณด๋ด์ง ์๋๋ค.
์์ ยท์ค๊ณฝยท๊ฒฝ๋ก ์์ฑ ๋ฐ์์ ํ์ธํ ๋ค ๊ธฐ๋ณธ ๋ช
๋ น์ผ๋ก ์ ์ฒด ๋๊ธฐํ๋ฅผ ์์ํ๋ค.
์ดํ ๊ฐ์ ๋ช
๋ น์
`--interval-seconds 30`์ ์ถ๊ฐํ๋ฉด ๊ณ์ ๋๊ธฐํํ๋ค. ์ ์ก ์ฑ๊ณต ๊ธฐ๋ก์
`~/.local/share/demoservice-sync/state.sqlite3`์ ์ ์ฅ๋์ด ๋ณ๊ฒฝ๋ GPX๋ง ๋ค์
๋ณด๋ธ๋ค. ์ ์ก ์ค๋ฅ๋ ๋ค์ ์ฃผ๊ธฐ์ ์ฌ์๋ํ๋ค. Lab ์๋ฒ๊ฐ ์ฌ์์๋ ๋ค ์๋์ผ๋ก
์คํํ๋ ค๋ฉด Lab ์ด์ ํ๊ฒฝ์์ ๋ณ๋ ์์ ์ค์ ์ด ํ์ํ๋ค.
ํ์ฌ `completion.json`์ด ์๋ ๋์ ์๋ฃ๋ ์ค๊ฐ ์น์ธ๋ณธ์ผ๋ก ํ์ํ๋ค.
์์ ํ ์น์ธ ๋ชฉ๋ก์ด ํ์ธ๋ ๊ฒฝ์ฐ์๋ง ๋นํ์ฑํ๋ฅผ ๋ฐ์ํ๋ค. ์ด ๋์ ์ถ๊ฐ๋
๊ธฐ์กด HGB ๋ชจ๋ธ์ ์ฌํ์ตํ์ง ์๋๋ค. ์ ๋ผ๋ฒจ์ ์ถ๊ฐํ๋ ค๋ฉด ๋ชจ๋ธ๊ณผ ์๋น์ค
๋ผ๋ฒจ ์ ์๋ ํจ๊ป ๊ฐฑ์ ํด์ผ ํ๋ค.
|