一本 229 頁的型錄進去，逐 SKU 的圖、貨號、色名、規格、價格出來。
四階段管線 · Stage 0 幾何索引 → Stage 1 選頁 → Stage 2 抽變體 → Stage 3 裁圖 → Stage 4 仲裁
- 299本實體型錄語料
- 15+個國際品牌
- 4.2 GB原始檔案量
- 229單本最高頁數
以上為建置這條管線時所使用的語料規模，不是客戶數也不是績效數字。
一本型錄進來會發生什麼事
以下五段是這條管線的實際執行順序。每一段都會說：這一階段在解決什麼、用了什麼技術、以及它失敗的時候會發生什麼事。最後一項通常比前兩項重要。
Stage 0 — 先把版面變成幾何，再談辨識
這一階段解決什麼
PDF 看起來是一頁圖，實際上是一組有座標的物件。色票是內嵌的 raster 圖，或是一個向量填色矩形——這兩件事 PDF 自己知道。在問模型任何問題之前，先把這份知識拿出來。
用什麼技術
MuPDF 逐頁建立幾何索引：每一頁的內嵌 raster 圖 bbox、每一個向量填色矩形 bbox。全程沒有模型參與，是決定性程式碼。
失敗時怎麼辦
有些型錄的色票不是圖也不是填色矩形，是整頁一張大圖（bookmatch 大板頁最常見）。這時 Stage 0 的索引會是空的，管線不會停，會把這一頁交給後面的 CV 快照路徑處理——也就是 Stage 3 的第三層。
Stage 1 — 整本逐頁分類，先決定哪些頁值得看
這一階段解決什麼
一本型錄裡真正是「色卡 / swatch 產品頁」的可能只有三成，其餘是封面、情境照、目錄、施工說明、品牌故事。把全部頁面都送去做逐變體抽取，是把預算燒在封面照片上。
用什麼技術
Gemini 2.5 Pro 整本逐頁分類，判定哪些是色卡產品頁；同時抽出品牌、系列、產地這一層的 series 級摘要。這一階段是模型在做主要判讀。
失敗時怎麼辦
兩種失敗被分開處理，因為處置方式完全不同：
- MAX_TOKENS（模型講到一半被截斷）→ 自動把這一批切成更小的 chunk 遞迴重跑。
- content filter（模型拒答）→ 先升溫重試，仍失敗才降級。
這兩種在 API 回應裡長得很像，如果不分類，你會用重試去解決一個永遠不會靠重試解決的問題。
把「模型講不完」跟「模型不講」當成同一件事處理，是 LLM 管線最常見的隱形失敗。
Stage 2 — 在色卡頁上逐一抽出每個產品變體
這一階段解決什麼
一張色卡頁上有 6 到 40 個變體。每個變體要對上：它的貨號 SKU、它的色名、以及它在頁面上的位置。前兩者是讀字，第三者是這一階段最容易出錯的部分。
用什麼技術
GPT-5.4 逐變體抽出 SKU + 色名 + 邊界框座標（0–999 正規化）。這一階段也是模型在做主要判讀。
失敗時怎麼辦
模型回的 bbox 不被直接信任。它會先跟 Stage 0 建立的幾何索引對位；對得上就用幾何座標，對不上才進入 Stage 3 的逐層退讓。模型的座標永遠只是候選，不是答案。
Stage 3 — 幾何裁圖，四層保真度逐級退讓
這一階段解決什麼
前面所有工作的產物，最後要變成一張真的可以放進商品頁的色票圖。裁歪一格，整批資料就報廢。
用什麼技術
四層 fallback，逐級退讓，且每一列輸出都帶 cropSource 欄位標明它是哪一層產出的：
失敗時怎麼辦
裁出來的形狀先過一道純幾何門檻：最小邊 < 8px，或長寬比 > 25 且最小邊 < 12px，直接丟棄。這擋掉髮絲條、空白格、被誤當成色票的 logo 框。門檻不是拍腦袋定的，是校準自真實語料裡一批 72 列的膨脹輸出。
第四層的 confidence 是硬寫 0.1 的常數，不是算出來的。這是刻意的：它在說「這一格是猜的，下游請當成猜的來用」。
| 層 | cropSource | 做什麼 | 保真度 |
|---|---|---|---|
| 3a | native-image | 直接取 PDF 原生圖層 | 最高（原始像素） |
| 3b | vector-render | 依向量填色矩形重繪 | 高（幾何精確） |
| 3c | cv-snap | 影像快照 + trim | 中（依賴邊緣偵測） |
| 3d | gpt-fallback | 裸用模型回的 bbox | 低（confidence 硬寫 0.1） |
Stage 4 — 文字層當裁判，模型不是最終權威
這一階段解決什麼
模型讀錯貨號是最貴的錯誤——因為它讀起來完全合理。AB-1203 讀成 AB-1208，沒有人會在驗收時發現。
用什麼技術
PDF 文字層是同一份文件裡的另一個獨立來源。模型讀到的貨號與文字層不一致時，這一列被標記 codeConflict，不靜默採信模型。
失敗時怎麼辦
codeConflict 不會被自動修掉，它會一路帶到輸出欄位裡。人可以只複核被標記的那幾列，而不是全部 800 列。
接著（Stage 5 後處理，同一區塊末段）
仲裁完之後還有一段全決定性的收攏工作：攤平成逐列結果、SKU 變體歸戶、跨頁的規格與價格歸屬、一列一尺寸展開、sha256 去重。這一段沒有任何模型參與，是純程式碼。
為什麼需要四層 fallback
這是全頁最值得被追問的一段。如果只做一層，你會在大部分型錄上得到漂亮的結果，然後在剩下那些上得到無聲的垃圾——不報錯，只是安靜地輸出錯的東西。
型錄的版面不是一種，是十種。同一條裁圖策略在 A 類情境照型上完美，在 F 類低對比無框色卡上會裁不出邊界，在 G 類大板一頁一色 bookmatch 上會把整頁當成一個色票。單一策略必然在某一類版型上崩掉，而且崩掉的時候不會報錯，會安靜地輸出錯的東西。
四層 fallback 的價值不在於「有四個備案」，在於三件事：
一、退讓是有順序的，而且順序是保真度順序。 不是誰先成功用誰，是先試最忠實的，不行才退到次忠實的。
二、退到第幾層是被記錄下來的。 cropSource 欄位跟著每一列輸出走。你可以查詢「這批裡有多少列是靠第四層產出的」，這個比例本身就是品質指標。
三、最後一層誠實地標了低分。 confidence 硬寫 0.1。它不假裝自己跟第一層一樣好。
- 沒有分層
- 一套策略打天下，某類版型整批壞掉且無聲
- 有分層但不記錄
- 壞的那批混在好的裡面，事後查不出哪些該複核
- 這條管線
- 每一列都知道自己是哪一層裁出來的
299 本型錄，歸納出十種版型
這條管線不是在三本樣本上寫出來的。語料規模與版型分類學是它的地基，也是它換產業時最需要重建的部分。
| 項目 | 數量 |
|---|---|
| 實體型錄 | 299 本 |
| 涵蓋國際品牌 | 15+ 個 |
| 原始檔案總量 | 4.2 GB |
| 單本最高頁數 | 229 頁 |
| 型錄評測樣本 | 67 個 |
| 訂單評測樣本 | 18 個 |
| 類 | 版型 | 對 Stage 3 裁切的具體挑戰 |
|---|---|---|
| A | 情境照型 | 產品被放在實景裡，沒有可裁的獨立色票 |
| B | 純 SKU 表格型 | 有文字無圖，Stage 3 幾乎無事可做 |
| C | 標準型（規則網格） | 最理想的一類，第一層即可完成 |
| D | 編號型鋪貼色卡 | 色票之間無框線，邊界靠留白判斷 |
| E | 超密集 contact sheet | 一頁數十格，退化裁切門檻在這一類最常被觸發 |
| F | 低對比無框色卡 | 色票與底色接近，CV 快照路徑不穩 |
| G | 大板一頁一色 bookmatch | 整頁一張大圖，容易被當成單一色票 |
| H | 規格表主導、極小縮圖 | 縮圖尺寸逼近 8px 門檻 |
| I | 藝術 lookbook 混排 | 無版面規律，Stage 1 選頁的判斷成本最高 |
| J | 網頁式 detail 圖 | 來源不是 PDF，走不同的取得路徑 |
這十類是從實際語料歸納出來的，每一類都標註了它對管線的具體挑戰。它綁磁磚建材語意——換一個產業，這張表要重建。
我們有評測集、有逐次評測報告、有加權準確度 / 完成率 / 平均延遲 / Token 成本 / 數值正確性這五個維度。
但這一頁不會給你一個準確率數字。型錄辨識的「正確」在不同版型上的定義不同，把它壓成單一百分比會誤導。我們能承諾的是：品質是可量測的，每一次改動都出報告，而且報告可以攤開給你看。
輸出長什麼樣
完整 schema 超過 40 個欄位。以下摘錄 17 個對接時最常用到的。
| 欄位 | 型別 | 說明 |
|---|---|---|
| brand | string | 品牌 |
| collection | string | 系列 |
| code | string | 貨號 SKU |
| color | string | 色名（中文） |
| color_en | string | 色名（英文） |
| sizes | string[] | 該 SKU 可用尺寸 |
| variantSizes | string[] | 該變體實際供應的尺寸 |
| price | number | null | 價格（無標價時為 null） |
| priceBand | string | null | 價格帶 |
| swatchImageUrl | string | 裁切後色票圖 URL |
| swatchSha256 | string | 色票圖雜湊（去重用） |
| swatchAvgColor | string | 色票平均色 |
| swatchBBox | number[] | 色票在原頁的座標 |
| confidence | number | 該列信心度 |
| cropSource | enum | native-image / vector-render / cv-snap / gpt-fallback |
| codeConflict | boolean | 貨號與 PDF 文字層不一致 |
| geoHit | boolean | 是否對上 Stage 0 的幾何索引 |
建議的接法：先用 cropSource 與 codeConflict 兩欄做人工複核佇列，其餘直接入庫。
兩個端點
對外是一組非同步 REST API。上傳回 202 加一個 catalog id，之後輪詢狀態。解析是長任務，不跑在 request 裡。
POST /api/catalogs/parse
Content-Type: multipart/form-data
file: <PDF> 上限 50 MiB
→ 202 Accepted { id }
GET /api/catalogs/:id
→ parse_status: pending → parsing → parsed → confirmed
↘ failed| parse_status | 意思 |
|---|---|
| pending | 已入佇列，尚未開始 |
| parsing | 解析中 |
| parsed | 解析完成，結果可讀 |
| confirmed | 已通過人工確認 |
| failed | 解析失敗，parse_error 有原因 |
完整 curl 範例與錯誤碼表在對外 API 文件裡（360 行），評估階段可索取。
這套系統不做什麼
不解析設計圖 / CAD。 這件事我們沒有做。系統裡有一個對應的型別佔位，但沒有任何實作，也不在目前的範圍內。
不是自研視覺模型。 判讀用的是 Gemini 與 GPT。我們自研的是管線——幾何索引、四層裁圖、文字層仲裁、跨頁歸戶、去重——不是模型。
不宣稱支援任何產業的型錄。 色名字典、尺寸文法、色票排序全部綁磁磚建材語意。換產業，管線骨架不動，但 prompt 與後處理字典要做一次語料校準。
不給準確率數字。 見上一區的說明。
不展示客戶語料。 建置這條管線所用的 299 本型錄屬於客戶的資料資產。這一頁只以量化敘述引用規模，不會有任何型錄頁面截圖。
你有一本型錄，我們跑一次給你看
帶一本你手上最難的型錄——最好是低對比無框色卡、或是一頁一色的大板。
我們跑一次，把每一列的 cropSource 與 codeConflict 攤開給你看。
寄一本最難的型錄過來跑完之前不需要簽任何東西。