然而，一旦你計劃打造具有專業影響力的技術品牌並開啟 Google AdSense（谷歌廣告聯盟）流量變現 時，就會遭遇一道無法逾越的規則紅線：Google AdSense 嚴格禁止針對 *.github.io 等免費二級子網域提交網站審查。此外，搜尋引擎累積的網域權重（Domain Authority）也無法沉澱為個人數位資產。要想通過商業化審查並沉澱 SEO 資產，擁有獨立的**頂級根網域（Apex Custom Domain，例如 globaldevlog.com）**是必經之路。

作為靜態網站工程化系列的第一篇，本文將以我們的技術部落格從 jbjihwan.github.io/global_blog 遷移至 https://globaldevlog.com 的實戰經歷為基礎，詳細拆解由 Porkbun + Cloudflare + GitHub Pages 構建的高可用三層生產架構與 DNS 深度配置要點。

1. 架構設計哲學：三層專業化高可用體系​

初學者在為 GitHub Pages 綁定獨立網域時，最常規的做法是在網域名稱註冊商處將 A 記錄 直接指向 GitHub 的 4 個固定 IP（185.199.108.153 等）。

這種傳統模式雖然簡單，但存在明顯的生產運維缺陷：

• 缺乏邊緣層 DDoS 攻擊防護與惡意爬蟲清洗；
• 遭遇故障或底層遷移時，DNS 生效速度緩慢；
• 無法對靜態資源（CSS/JS/圖片）進行靈活的邊緣 CDN 快取調優。

為此，我們將職責解耦為三個專業化的服務層級：

2. 第一步：Porkbun 網域購買與 Cloudflare 權威名稱伺服器委派​

1. 網域選購：在 Porkbun 檢索並購買心儀的頂級根網域（如 globaldevlog.com）。
2. 接入 Cloudflare：登入 Cloudflare 控制台，點擊 [新增網站] 輸入該網域，方案選擇 Free (免費版)。
3. 獲取分配的名稱伺服器：Cloudflare 會自動分配一對專有的權威 Nameservers，例如：

   roan.ns.cloudflare.com
   sneh.ns.cloudflare.com
   

4. 修改 Porkbun DNS 委派：進入 Porkbun 的網域管理面板，找到 Authoritative Nameservers 設定項，刪除 Porkbun 預設地址，填入 Cloudflare 分配的 2 個伺服器地址並儲存。通常在 5 到 15 分鐘內全球生效。

3. 第二步：Cloudflare CNAME 扁平化 (Flattening) 與 Full SSL 模式​

按照 DNS 國際標準（RFC 1034），根網域（@）必須包含 SOA 和 NS 記錄，因此傳統上無法直接配置 CNAME 記錄。

Cloudflare 的 CNAME 扁平化 (CNAME Flattening) 技術徹底解決了這一痛點：在 DNS 解析查詢時，Cloudflare 邊緣節點會在底層即時解析目標地址（username.github.io）對應的 IP，並以 A 記錄 的形式直接向客戶端應答，從而讓根網域完美享有 CNAME 的所有敏捷特性。

A. 配置 Cloudflare DNS 解析記錄​

在 Cloudflare 儀表板 [DNS] > [記錄] 中，新增以下兩條開啟代理的記錄：

必須點亮橘色雲朵：只有處於代理模式下，造訪流量才會經由 Cloudflare 全球 Anycast 節點接入，享受自動化邊緣 SSL 終結、Brotli 極速壓縮以及抗 DDOS 保護。

B. 設定 SSL/TLS 加密模式​

前往 Cloudflare 左側導覽列 [SSL/TLS] > [概述]：

• 將加密模式設為 Full (完全) 或 Full (Strict) (完全嚴格)；
• 確保從訪客瀏覽器到 Cloudflare、以及從 Cloudflare 到 GitHub Pages 源站的端到端 HTTPS 雙向鏈路均得到高強度加密。

4. 第三步：更新 Docusaurus 核心配置 (docusaurus.config.ts)​

當部落格從子目錄路徑（/global_blog/）整體遷移至獨立根網域時，必須相應修正 docusaurus.config.ts：

const config: Config = {
  title: 'Global Dev Blog',
  tagline: 'Engineering Deep Dives in AI, Robotics, Computer Vision',

  // 替換為全新的頂級自訂網域
  url: 'https://globaldevlog.com',
  // 從子目錄 '/global_blog/' 改為頂級根路徑 '/'
  baseUrl: '/',

  organizationName: 'jbjihwan',
  projectName: 'global_blog',
  trailingSlash: false,
  // ...
};

5. 第四步：徹底攻克 GitHub Pages 部署後網域被重設的隱蔽陷阱 (static/CNAME)​

在配置 GitHub Pages 自訂網域時，幾乎所有開發者都踩過這個著名的“大坑”：

1. 在 GitHub 儲存庫頁面的 Settings > Pages > Custom domain 中手動填入 globaldevlog.com 並儲存生效；
2. 本地寫完新文章，終端執行 npm run deploy 重新部署；
3. 部署一完成，重新整理 GitHub 頁面發現自訂網域輸入框再次變成了空白，線上網站瞬間爆出 404 錯誤或 SSL 憑證失效警告！

陷阱根源​

Docusaurus 的發布指令碼在編譯完成後，會將 build/ 目錄強制推送到 gh-pages 分支（git push --force）。如果該打包產物的根目錄下缺少純文字 CNAME 檔案，GitHub 會預設判定使用者已主動取消了自訂網域綁定。

永久解決方案​

在專案的 static/ 目錄下建立一個名為 CNAME 的純文字檔案（無任何副檔名），內容僅寫入一行你的網域：

globaldevlog.com

由於 Docusaurus 在建構時會自動將 static/ 目錄下的所有檔案原封不動複製到打包輸出根目錄，因此每次執行部署時，CNAME 檔案都會被永久提交至 gh-pages 分支的最頂層，網域綁定永不丟失。

6. 生產環境連通性驗證​

在專案根目錄下執行部署指令：

npm run deploy

部署成功後，在終端機透過 curl 命令驗證 HTTP 狀態碼與 SSL 憑證鏈回應：

curl -I https://globaldevlog.com
# HTTP/2 200
# server: cloudflare
# strict-transport-security: max-age=31536000

curl -I https://www.globaldevlog.com
# HTTP/2 200 (或 301 重新導向至根網域)

🔜 下篇預告​

獨立網域成功上線後，真正的商業化與多引擎搜尋獲客工作才剛剛拉開序幕：

• 第二篇：[靜態網站商業化 #2] Docusaurus 接入 Google AdSense 審查實戰：解決 ads.txt 404 爬取故障與非同步指令碼安全植入
• 第三篇：[全球多搜尋引擎 SEO #3] Google、Naver 與 Bing 站長平台權威配置：Sitemap 無法刪除之謎與主機層級報錯排查

📌 核心重點 (TL;DR)

• 問題 (Problem)：與傳統動態 CMS (WordPress) 不同，代管在 GitHub Pages 或 Cloudflare Pages 上的 Docusaurus、Next.js 等靜態網站產生器 (SSG) 極易遭遇惡名昭彰的 「收益受損風險：缺少 ads.txt 檔案」 警報，並因客戶端融合延遲或 WAF 誤殺導致所有權審核失敗。
• 解決方案 (Solution)：利用 Docusaurus 原生的 headTags 設定將驗證中繼標籤直接注入靜態 HTML，透過 static/ads.txt 實作根目錄資產部署，並在 Cloudflare WAF 中為 Googlebot-AdsTxt 抓取爬蟲設定放行白名單。
• 實驗結果 (Result)：實作爬蟲 100% 順暢存取、/ads.txt 零 404 回應，在確保 Lighthouse 效能與 SEO 得分穩定在 95 分以上的同時，一次性符合 AdSense 審核規範。

1. 靜態網站 (SSG) 整合 AdSense 面臨的獨特挑戰​

將開發部落格從預設的子路徑 (username.github.io/blog) 遷移至獨立頂級網域 (https://globaldevlog.com) 後，下一步核心戰略便是接入 Google AdSense 商業化廣告。然而，靜態網站在架構上面臨著以下特殊瓶頸：

1. 缺乏伺服器端資料庫與動態外掛程式支援：WordPress 可以透過 Site Kit 外掛程式一鍵注入程式碼並產生 ads.txt，而在 Docusaurus 中，所有資源必須在編譯階段嚴格固化。
2. 客戶端融合 vs 靜態 Head 注入：若透過 React 元件生命週期動態載入指令碼，搜尋引擎爬蟲在執行 JavaScript 之前可能就因抓取逾時而判定審核失敗。
3. ads.txt 404 抓取陷阱：編譯產物路徑錯配將導致 AdSense 爬蟲 (Googlebot-AdsTxt) 存取 https://yourdomain.com/ads.txt 時傳回 404，導致網域收益被全量凍結。

2. 第一步：在 Docusaurus 中注入所有權驗證中繼標籤​

在 AdSense 主控台（網站 > 新增網站）提交網域後，Google 會要求驗證網站所有權。對於靜態部落格而言，透過 docusaurus.config.ts 的 headTags 選項注入靜態 <meta> 標籤是最優雅且零效能損耗的解決方案。

📐 設定檔程式碼 (docusaurus.config.ts)​

import type {Config} from '@docusaurus/types';

const config: Config = {
  title: 'Global Dev Blog',
  url: 'https://globaldevlog.com',
  baseUrl: '/',

  // 注入 Google AdSense 所有權驗證中繼標籤
  headTags: [
    {
      tagName: 'meta',
      attributes: {
        name: 'google-adsense-account',
        content: 'ca-pub-XXXXXXXXXXXXXXXX', // 替換為您的 AdSense 發布商 ID
      },
    },
  ],

  // ... 其它設定項
};

export default config;

💡 為何優先選用 headTags 而非 scripts？​

• 零執行階段效能開銷：無需在審核初期預先載入重達約 120 KB 的 adsbygoogle.js 指令碼套件，避免拖慢 PageSpeed 跑分。
• 100% 確定性抓取：中繼標籤直接編譯嵌入到伺服器端預渲染的靜態檔案 (build/index.html) 中，確保 Google 審核機器人瞬間驗證通過。

3. 第二步：徹底根除 ads.txt 404 抓取陷阱​

提交審核後，發布商最常遭遇的紅色警報莫過於：

⚠️ 「收益受損風險：您需要解決一些 ads.txt 檔案問題，以免對您的收入造成嚴重影響。」

其誘因極其明確：Google 的 Googlebot-AdsTxt 爬蟲請求 https://globaldevlog.com/ads.txt 時遭遇了 HTTP 404 錯誤。

🛠️ 基於 static/ads.txt 實作根目錄直接部署​

Docusaurus 在執行編譯時，會將專案根目錄下 static/ 中的所有檔案直接原樣複製到產物根路徑 (build/)。

1. 新增 static/ads.txt 檔案：

   google.com, pub-XXXXXXXXXXXXXXXX, DIRECT, f08c47fec0942fa0
   

   (請將 pub-XXXXXXXXXXXXXXXX 替換為您個人的發布商 ID)

2. 確認檔案並部署上線：

   npm run deploy
   

🔍 部署後連通性驗證​

在終端機中利用 curl 檢查回應標頭：

curl -I https://globaldevlog.com/ads.txt

標準回應輸出：

HTTP/2 200
content-type: text/plain; charset=utf-8
cache-control: max-age=600
server: cloudflare

同時請確認存取 https://www.globaldevlog.com/ads.txt 時能正常執行 301/308 重新導向至根網域。

4. 第三步：Cloudflare WAF 與邊緣安全防護調優​

若您的網域開啟了 Cloudflare 的橘色雲朵代理，其內建的 Bot 防禦規則可能會意外攔截 Google 的自動抓取程式。

flowchart LR
    Bot["Googlebot-AdsTxt 爬蟲"] --> Edge["Cloudflare 邊緣 WAF"]
    Edge -->|"校驗 User-Agent 與 ASN"| Rule{"WAF 安全防火牆規則"}
    Rule -->|"Bot Fight Mode (誤報)"| Drop["403 Forbidden / 質詢攔截"]
    Rule -->|"放行繞過規則"| Origin["GitHub Pages 來源站 (/ads.txt)"]

Cloudflare WAF 自訂規則設定​

• 規則運算式：

  (http.user_agent contains "Googlebot-AdsTxt") or (http.user_agent contains "Mediapartners-Google")
  

• 執行動作：跳過 (Skip) — 繞過 WAF 質詢及速率限制，確保爬蟲順暢擷取 ads.txt。

5. AdSense 首次審核通關必備四大準則​

6. 總結與後續規劃​

透過 headTags 完成中繼標籤校驗、static/ads.txt 根目錄部署以及 Cloudflare WAF 爬蟲白名單調優，您的靜態技術部落格現已具備堅不可摧的 AdSense 準入技術條件。

• 在下一期 第 3 篇 中，我們將深入剖析 Google Search Console、Naver Search Advisor 與 Bing Webmaster Tools 的 6 語言站台地圖多路提交與 SEO 自動化管線！

📌 Global Dev Blog 精選技術推薦：
• Global Dev Blog - GitHub Pages 綁定自訂網域與 Cloudflare DNS 實戰
• Global Dev Blog - 靜態網站安全強化與 npm audit 弱點真相
• 存取支援 6 大語種的 Global Dev Blog 首頁

將靜態文件或技術部落格遷移至獨立網域，絕非只是簡單修改一條 DNS 解析記錄。它涉及網域註冊商的權威名稱伺服器委派、邊緣 SSL 終結、規範化重新導向、自動化發布商 ads.txt 託管，以及跨越各大搜尋引擎站長工具平台特有的 UI 隱蔽陷阱。

在本指南中，我們將全面復盤從 jbjihwan.github.io/global_blog 零停機遷移至 https://globaldevlog.com 的端到端全過程，涵蓋高可用 DNS 架構設計、AdSense 審核合規設定，以及在 Google Search Console、Naver Search Advisor 和 Bing Webmaster Tools 中遇到的真實索引問題的排查方案。

1. 架構戰略：Porkbun + Cloudflare + GitHub Pages​

將根網域（例如 globaldevlog.com）綁定至 GitHub Pages 時，最原始的方法是將 A 記錄 直接指向 GitHub 官方的 4 個 Anycast IP（185.199.108.153 等）。這種方式雖然可用，但缺失了現代雲端必備的邊緣安全防護、DDoS 攻擊清洗以及自動化 HTTPS 憑證續期。

為此，我們構建了高可用的三層解耦生產架構：

Porkbun 名稱伺服器委派​

在 Porkbun 網域管理控制台中，將預設的註冊商 Nameservers 替換為 Cloudflare 分配的專用邊緣伺服器：

NS: roan.ns.cloudflare.com
NS: sneh.ns.cloudflare.com

Cloudflare CNAME 扁平化設定​

根據 RFC 1034 規範，根網域（@）因需共存 SOA/NS 記錄而在傳統上無法配置 CNAME。Cloudflare 藉助其專利技術 CNAME 扁平化 (CNAME Flattening) 完美解決了這一限制，可無縫將 @ 解析指向 GitHub Pages：

• Type: CNAME | Name: @ | Target: jbjihwan.github.io | Proxy status: Proxied (已開啟代理/橘色雲朵)
• Type: CNAME | Name: www | Target: jbjihwan.github.io | Proxy status: Proxied (已開啟代理/橘色雲朵)
• SSL/TLS 模式: 設定為 Full (完全) 或 Full Strict (完全嚴格)，確保端到端的 HTTPS 雙向加密傳輸。

2. Docusaurus 核心配置遷移​

為了平滑地將子路徑路由（/global_blog/）整體切換為獨立網域根路徑（/），我們需要更新 docusaurus.config.ts：

const config: Config = {
  title: 'Global Dev Blog',
  url: 'https://globaldevlog.com',
  baseUrl: '/',
  organizationName: 'jbjihwan',
  projectName: 'global_blog',
  trailingSlash: false,
  // ...
};

靜態 CNAME 檔案配置​

GitHub Pages 依靠部署分支根目錄下的純文字 CNAME 檔案來識別流量歸屬。必須將其放置在 static/CNAME：

globaldevlog.com

執行 npm run deploy 時，Docusaurus 會自動將 static/ 目錄中的所有檔案拷貝到編譯輸出的根目錄，確保 GitHub 路由引擎始終將指向 globaldevlog.com 的造訪請求正確映射到該儲存庫。

3. 靜態部落格 Google AdSense 審核配置​

Google AdSense 審核的核心流程包括：確認網站所有權、檢測合規的發布商非同步指令碼、以及抓取位於網站根目錄下的 ads.txt 檔案。

A. 非同步植入發布商指令碼​

在 docusaurus.config.ts 的 scripts 陣列中非同步引入 Google AdSense 載入器：

  scripts: [
    {
      src: 'https://pagead2.googlesyndication.com/pagead/js/adsbygoogle.js?client=ca-pub-4654073335496617',
      async: true,
      crossorigin: 'anonymous',
    },
  ],

B. 根目錄部署 ads.txt 並完成線上驗證​

在 static/ads.txt 中填入官方認證的發布商憑證：

google.com, pub-4654073335496617, DIRECT, f08c47fec0942fa0

部署後透過終端機 curl 立即驗證 HTTP 200 狀態碼：

curl -I https://globaldevlog.com/ads.txt
# HTTP/2 200
# content-type: text/plain; charset=utf-8

4. 多搜尋引擎 SEO 實戰與疑難雜症排查​

向各大搜尋引擎提交網站地圖時，各家平台往往有著獨特的互動規則和容易誤踩的 UI 陷阱：

A. Google Search Console：無法刪除錯誤網站地圖的互動陷阱​

在提交多語言網站地圖（sitemap.xml, ko/sitemap.xml, ja/sitemap.xml, es/sitemap.xml 等）時，若不慎誤將網站根網址 https://globaldevlog.com/ 作為網站地圖提交，會在列表裡留下永久性的“包含錯誤”警報。

許多開發者點擊該行表格右側的縱向三點圖示（⋮），卻發現彈出的選單中只有反灰的“查看網頁編入索引情況”，完全找不到任何刪除按鈕。

解決策略：

1. 切勿點擊表格行最右側的選單按鈕。請直接點擊該網站地圖的網址文字本身，進入網站地圖詳情頁面。
2. 在詳情頁面右上角（靠近搜尋欄下方區域），點擊頁面頂部的三點圖示（⋮）。
3. 在彈出的選單中點擊 [刪除網站地圖]，即可乾淨徹底地移除該錯誤項目。
4. 若多語言網站地圖（如 es/sitemap.xml）因網路或 DNS 快取抖動偶發“無法抓取”，直接在上方“新增網站地圖”輸入框中重新輸入並提交，系統會立即發起二次抓取並重新整理為成功狀態。

B. Naver Search Advisor：“請按主機層級輸入 URL”​

Naver 佔據韓國本土主流搜尋份額。在其站長平台操作時需注意：

1. 主機層級報錯：在初始“網站登記”彈窗中直接提交 https://globaldevlog.com/sitemap.xml 會觸發彈窗警告：“URL을 호스트 단위로 입력해주세요 (請按主機層級輸入 URL)”。該視窗僅用於登記主網域（https://globaldevlog.com）。
2. 所有權雙保險：同時部署 HTML 校驗檔案（static/naver<hash>.html）與頁面元標籤（themeConfig.metadata），確保無論採用何種檢驗機制均能秒級通過。
3. 提交網站地圖與 RSS：在管理控制台（點擊網站列表中的網域）：
   • 進入 [請求] > [提交網站地圖]：輸入 sitemap.xml
   • 進入 [請求] > [提交 RSS]：輸入 https://globaldevlog.com/blog/rss.xml
4. 加速 Yeti 蜘蛛抓取：在 [請求] > [網頁抓取] 中，手動提交核心路徑（blog, ko/blog 等），促使搜尋引擎蜘蛛快速造訪。

C. Bing 站長工具與 AI 搜尋 (Copilot / ChatGPT Search) 接入​

Bing Webmaster Tools 不僅為必應搜尋提供數據，同時也是 Copilot、ChatGPT Search、Yahoo 和 DuckDuckGo 的底層索引源泉。

• GSC 一鍵匯入：直接授權 Google 帳號登入，可瞬間同步已驗證的網域所有權與全部網站地圖。
• 跨越 48 小時數據同步延遲：GSC 自動同步通常需要 24 至 48 小時。直接進入左側 [Sitemaps] > 點擊 [Submit sitemap] 手動錄入 https://globaldevlog.com/sitemap.xml，即可免去等待，即刻驅動必應爬蟲全量入庫。

5. 生產環境最終檢查清單​

在正式推廣你的獨立網域之前，請確保以下項目全部核驗通過：

• DNS 解析狀態：globaldevlog.com 和 www 均在無 SSL 憑證告警的前提下正常回應。
• 規範化 CNAME：static/CNAME 已打包部署至 GitHub Pages 源站。
• AdSense 核心資產：https://globaldevlog.com/ads.txt 正常返回 HTTP 200 且發布商 ID 完全符合。
• 多語言網站地圖：各語言專屬網站地圖（/sitemap.xml, /ko/, /ja/, /es/, /zh-Hans/, /zh-Hant/）均返回 HTTP 200。
• 三大搜尋引擎收錄：Google、Naver 和 Bing 均已成功完成所有權驗證，RSS 訂閱源均處於活躍抓取狀態。

憑藉這套現代化的工程基礎設施，你的靜態部落格不僅享有邊緣 CDN 的極致載入速度、零伺服器帳單開支，更獲得了覆蓋全球主要語系的頂級搜尋可見度，並為 Google AdSense 商業化變現奠定了堅實的基石。

45 vulnerabilities (15 moderate, 15 high, 15 critical)
To address all issues (including breaking changes), run:
  npm audit fix --force

看到諸如 Critical (嚴重)、Remote Code Execution (遠端代碼執行/RCE) 和 Prototype Pollution (原型鏈污染) 這樣的高危詞彙，人類的第一反應往往是毫不猶豫地敲下 npm audit fix --force，試圖讓這些刺眼的紅字立刻消失。

然而，在基於 靜態網站產生器 (SSG)（例如部署在 GitHub Pages 或 AWS S3 上的 Docusaurus、Next.js 或 Hugo）的世界裡，這樣做往往是一個嚴重的工程誤判——它不僅無法真正提升你的安全水位，反而會破壞生產環境的建構流程。

在本文中，我們將深入剖析 靜態網站的威脅模型 (Threat Model)，揭示打包編譯期漏洞與線上伺服端漏洞的本質差異，並分享一套經生產檢驗的 4 層靜態安全加固藍圖，保護真正核心的資產：你的機密憑證、訪客隱私以及程式碼庫完整性。

1. 核心工程權衡概述​

1. 編譯期工具不等於線上執行時：在 npm audit 中被標記的依賴套件（例如 tinypool、serialize-javascript、postcss-selector-parser）是僅在開發者本地執行 npm run build 時被 Node.js 呼叫的編譯打包依賴。
2. CDN 邊緣零後端服務：一旦編譯完成，GitHub Pages 分發的僅僅是不可變的純靜態 HTML、CSS 和客戶端 JavaScript。在生產環境中，不存在任何常駐執行的 Node.js 守護程序，沒有任何開放監聽的後端連接埠，也完全沒有資料庫連線。
3. --force 的破壞性：盲目執行 npm audit fix --force 會強行降級核心框架（例如將 Docusaurus 回退到舊版本），破壞對 React 19 的相容性、MDX v3 渲染管線以及未來功能開關架構。
4. 靜態網站真正的攻擊面：靜態部落格面臨的真正威脅是 公開 Git 提交歷史中的 API 金鑰外洩、資料集中的個人隱私 (PII) 暴露 以及 客戶端跨域數據洩漏。

2. 深度拆解 45 個漏洞：編譯期 vs 執行時​

讓我們審查一下稽核日誌中實際報告的典型 CVE：

A. Tinypool 原型鏈污染 (GHSA-5gmw-xhrv-c9v3 - Critical 嚴重)​

• 漏洞原理：如果向 tinypool 的 Worker 初始化選項中傳入不可信的使用者輸入，攻擊者可污染 Object.prototype。
• 靜態網站現實：tinypool 僅在 @docusaurus/faster 內部用於在建構期間跨 CPU 核心並行處理打包任務。所有的輸入參數均嚴格來自於開發者自身的 docusaurus.config.ts。線上外部訪客根本無法向你本地的 CPU 程序池發送任何 HTTP 負載。

B. Serialize-JavaScript 遠端代碼執行 (GHSA-5c6j-r48x-rmvq - High 高危)​

• 漏洞原理：透過精心建構的 RegExp 標誌或序列化日期實作遠端代碼執行。
• 靜態網站現實：Webpack 僅使用它將內部編譯區塊序列化為靜態 .js 代碼束。一旦寫入 build/ 目錄，這些 JavaScript 僅僅是透過 HTTPS 分發的靜態資源檔案，伺服端完全不發生任何反序列化過程。

C. PostCSS Selector Parser CPU 耗盡 (GHSA-rj75-hqrm-r3gf - Moderate 中危)​

• 漏洞原理：解析器在處理特定平鋪選擇器時具有二次方時間複雜度，可透過惡意 CSS 字串導致拒絕服務 (DoS)。
• 靜態網站現實：被解析的 CSS 檔案完全是專案自身的主題樣式表（custom.css）。除非攻擊者擁有向你 Git 儲存庫推送程式碼的權限，否則建構機器永遠不會解析不可信的外部 CSS。

在這種情況下強行執行 npm audit fix --force，npm 會嘗試將 @docusaurus/core 從 3.10.2 強制降級到 3.7.0。這會直接導致 Docusaurus v4 特性與 React 19 渲染徹底崩潰——為了修復一個在你的物理架構中根本不可能被觸發的漏洞，反而親手向生產程式碼中引入了致命 Bug。

3. 真正重要的防線：4 層靜態安全加固藍圖​

如果建構工具漏洞風險極低，靜態網站工程師應該將安全精力投入到哪裡？以下是本部落格實施的縱深防禦體系。

第一道防線：Git 提交前自動化金鑰掃描 (Pre-Commit Secret Scanning)​

對於公開開源的技術部落格而言，最大的滅頂之災是在 Git 提交中不慎洩露 OpenAI 金鑰 (sk-...)、GitHub Token (ghp_...) 或 AWS 存取憑證 (AKIA...)。

我們編寫了自動化稽核指令碼（tools/audit_security.py），利用 Git 的底層物件資料庫，在提交前掃描所有追蹤檔案：

PATTERNS = [
    (r'(?i)(api[_-]?key|secret|token|password|auth|bearer)\s*[:=]\s*["\']([^"\']{8,})["\']', "Potential Key Assignment"),
    (r'ghp_[a-zA-Z0-9]{36}', "GitHub Personal Access Token"),
    (r'sk-[a-zA-Z0-9]{32,}', "OpenAI API Key"),
    (r'AIzaSy[a-zA-Z0-9_-]{33}', "Google API Key"),
    (r'AKIA[0-9A-Z]{16}', "AWS Access Key"),
    (r'-----BEGIN\s+(RSA\s+)?PRIVATE\s+KEY-----', "Private Key Certificate"),
]

在每次程式碼發布前執行此稽核工具，確保硬編碼的敏感 Token 絕不會逃逸至遠端公開儲存庫。

第二道防線：個人身分識別資訊 (PII) 嚴格去識別化​

在發布涉及 AI 資料集盲測的技術專欄時（例如我們的 23 篇心靈守護者心理諮商系列或 5 篇 ANPR 視覺 AI 系列）：

• 合成資料優先：所有心理對話案例均由大模型流程（synth_gen）端到端合成，絕不使用真實患者對話記錄，從源頭上杜絕醫療隱私外洩。
• 正則敏感資訊排查：自動化校驗所有 Markdown 內容，防範電話號碼或身分登記字號等敏感欄位意外流出。

第三道防線：深度強化的 .gitignore 規範​

許多標準的 .gitignore 僅僅忽略了 .env.local，卻留下了 .env。我們將設定進行了工業級強化，徹底阻斷敏感金鑰、憑證及原始分析記錄：

# 環境變數與機密憑據保護
.env
.env.*
*.pem
*.key
*.pfx
*.cert
*credential*
*.secret

# 資料分析原始匯出檔案
*.csv

# 廢棄的舊版本範本
_old/

第四道防線：客戶端隱私保護與 Iframe 沙盒隔離​

即使沒有後端伺服器，靜態網站也必須尊重訪客隱私並防止數據外洩：

1. 嚴格的 Referrer 策略：在 docusaurus.config.ts 的 <head> 中注入安全請求頭：

   themeConfig: {
     metadata: [
       { name: 'referrer', content: 'strict-origin-when-cross-origin' },
     ],
   }
   

   確保訪客點擊外鏈跳轉時，瀏覽器會自動截斷部落格的具體文章路徑及參數，防止內部 URL 洩漏。

2. Giscus 留言系統沙盒化：透過 GitHub Discussions 承載互動評論時，配置：

   • emitMetadata="0"：禁止 iframe 廣播跨頁面訊息，防範第三方指令碼窺探討論詳情；
   • loading="lazy"：延遲載入留言模組，直到訪客真正滾動至文章底部才觸發執行。

4. 給開發者的核心啟示​

• 面對 npm audit 保持清醒：時刻區分 建構期依賴 與 線上執行時依賴。
• 警惕 --force 陷阱：自動降級往往會在修復虛幻安全隱患的同時，親手向生產環境注入真實的破壞性 Bug。
• 聚焦真正的攻擊面：建立程式碼提交前金鑰掃描、清洗敏感資料集、配置嚴密的客戶端隱私策略，守護真正的數位核心。

📌 核心要點 (Key Takeaways)

• 問題痛點：由於車輛顛簸、車身偏航角、路面反光及運動模糊，單幀靜態 OCR 辨識不可避免會出現偶發誤讀（例如將 64가1511 誤判為 64아1511 或 24가1511）。
• 解決方案：引入韓國車牌強語法正規約束 (^\d{2,3}[가-힣]\d{4}$)，並設計基於 7 幀時間緩衝區的滑動視窗多數表決引擎 (plate_confirm_threshold=3)。
• 落地成效：經歷了從 6 月 5 日的最初全螢幕亂碼 (ACCIIXOY-1Z01...)，到 6 月 7 日以 99.4% 的超高信賴度確定性鎖定最終車牌 64가1511，完整走通了 11 輪 (v01 至 v11) 系統級工程迭代。

1. 韓國車牌語法校驗與 EasyOCR 調校​

韓國機動車輛牌照遵循非常嚴格的法定語法規則：

標準語法結構：[2位或3位數字] + [1個韓文字母] + [4位數字]
標準範例：64가1511, 123가4567

在推論管線末端，我們將提取到的車牌影像送入經過自訂初始化的 EasyOCR 辨識器，並使用精準的正規表示式清洗誤檢文字：

import easyocr
import re
from collections import deque, Counter

# 初始化雙語辨識器，強制開啟 GPU 加速
reader = easyocr.Reader(['ko', 'en'], gpu=True)

def parse_korean_plate(plate_img):
    # 關閉細節返回以最小化資料傳輸開銷
    results = reader.readtext(plate_img, detail=0)
    raw_text = "".join(results).replace(" ", "")
    
    # 韓國車牌專屬正則匹配模式
    pattern = r'(\d{2,3}[가-힣]\d{4})'
    match = re.search(pattern, raw_text)
    return match.group(1) if match else None

2. 基於時序滑動視窗的多數表決引擎 (Temporal Majority Voting)​

為了抵禦單幀畫面偶然的辨識抖動，我們在時間維度上維護一個定長的滑動歷史佇列（Sliding History Queue）：

# 維護最近 7 幀檢測結果
plate_history = deque(maxlen=CONFIG["plate_history_size"])  # 7
confirmed_plate = None

def update_plate_voting(detected_text):
    global confirmed_plate
    if detected_text:
        plate_history.append(detected_text)
        
    # 當佇列累計達到確認閾值時發起統計表決
    if len(plate_history) >= CONFIG["plate_confirm_threshold"]:
        counts = Counter(plate_history)
        most_common_plate, count = counts.most_common(1)[0]
        
        # 僅當同一車牌獲得 3 票或以上贊成時，方才判定為最終確信結果
        if count >= CONFIG["plate_confirm_threshold"]:
            confirmed_plate = most_common_plate
            
    return confirmed_plate

3. 從 v01 到 v11 的 11 輪工程演進實錄 (6月5日 至 6月7日)​

系統 log.txt 真實見證了這套演算法管線的淬鍊全過程：

4. 總結與未來展望​

至此，在這個由 5 篇深度專欄構成的 ANPR 視覺工程系列中，我們完整構建了一套涵蓋 動態車道線擬合、多邊形 IoU 壓線侵入判定、分層目標定位、CSRT 目標追蹤、EDSR 深度超解析度重建與時序多數表決 OCR 的工業級端到端視覺系統。這套架構為邊緣運算裝置上的高精度即時智慧交通檢測（ITS）提供了經過實戰檢驗的標準範式。

📌 核心要點 (Key Takeaways)

• 問題痛點：從高速行車記錄器畫面裁剪出的遠距離車牌區域往往不足 40x20 像素，且伴隨嚴重的 H.264 編碼巨集區塊效應；傳統的雙三次插值（Bicubic）演算法只會讓字體邊緣更加模糊，無法還原字元有效筆畫。
• 解決方案：引入移除了 Batch Normalization 層以保留高動態像素範圍的 EDSR_x4 深度殘差模型 (EDSR_x4.pb)，並結合連續 3 至 5 幀的時序多幀加權疊加（Multi-Frame Image Stacking）技術。
• 落地成效：車牌像素密度提升 4 倍，筆畫邊緣顯著銳化，使得下游 EasyOCR 對韓文字元的辨識準確率從最初的 32% 飆升至 91% 以上。

1. 光學解析度極限與深度超解析度的必要性​

在惡劣的高速公路行車環境下，即使透過 YOLOv5 精準裁剪出車牌區域，常規 OCR 依舊頻繁失效：

1. 傳統雙三次插值失效：數學插值演算法僅在相鄰像素間進行線性過渡，根本無法憑空“腦補”出高頻邊緣特徵。
2. H.264 壓縮與感光雜訊：視訊編碼壓縮帶來的馬賽克雜訊會導致字元筆畫斷裂粘連。

為此，我們在推論管線中透過 OpenCV DNN Super-Resolution 模組 深度整合了經過精細預訓練的 EDSR_x4 深度模型：

import cv2
from cv2 import dnn_superres

def init_super_resolution_engine(model_path="EDSR_x4.pb"):
    # 建立深度學習超解析度引擎介面
    sr = dnn_superres.DnnSuperResImpl_create()
    sr.readModel(model_path)
    
    # 配置模型架構為 edsr，放大倍率為 4x
    sr.setModel("edsr", 4)
    
    # 強制將推論後端綁定至 CUDA GPU 加速
    sr.setPreferableBackend(cv2.dnn.DNN_BACKEND_CUDA)
    sr.setPreferableTarget(cv2.dnn.DNN_TARGET_CUDA)
    return sr

2. 基於時序多幀影像疊加的物理級降噪​

由於車載攝影機感光晶片在每一幀產生的電子熱雜訊是高斯隨機分佈的，而真實車牌的物理文字在連續幀內具有空間相關性。我們透過對齊連續 $N$ 幀車牌補丁進行加權均值疊加：

I_stacked(x, y) = (1 / N) * Σ Warp(I_i(x, y))

這種時序疊加機制不僅在不損失邊緣銳度的前提下消除了高達 70% 的高頻隨機雜訊，還顯著增強了字元與反光底板之間的明暗對比度。

3. 下篇預告​

在接下來的第 5 篇（收尾篇）中，我們將全面揭秘 韓國車牌語法校驗、EasyOCR 字元辨識調校 以及核心的 時序滑動視窗多數表決引擎，復盤從最初一堆全螢幕亂碼到最終百分之百鎖定目標車牌（64가1511）的完整工程突破歷程。

📌 核心要點 (Key Takeaways)

• 問題痛點：在未經裁剪的 640x480 原圖上直接搜尋僅佔 30x15 像素的微小車牌，會因路邊廣告牌、交通指示牌與建築物反光引發海量誤報，且模型全圖高解析度推論會導致幀率暴跌至 10 FPS 以下。
• 解決方案：設計“兩階段分層（Hierarchical）定位”方案：先由輕量級 YOLOv3-tiny 圈定車輛主體邊界框，再將裁剪出的車輛局部 ROI 送入精調的 YOLOv5 車牌專用檢測器 (lp_det.pt, 信賴度=0.6)；同時引入 OpenCV CSRT 相關濾波追蹤器，每隔 15 幀僅重檢一次。
• 落地成效：徹底消除了 98% 的背景干擾誤報，GPU 計算開銷驟降 80%，在邊緣運算裝置上穩定跑滿 50+ FPS 的極速即時追蹤。

1. 全圖檢測的致命陷阱與分層檢測的破解之道​

在車載行車記錄器畫面中，嘗試在全螢幕畫面上直接執行車牌檢測存在兩大致命缺陷：

1. 複雜背景雜訊吞噬特徵：街邊商店招牌上的文字、公車車身廣告都會導致車牌檢測器頻繁誤觸發。
2. 下取樣特徵嚴重遺失：當 640x480 的影像被下取樣至模型輸入尺寸（如 640x640）時，本就只有幾十像素的微小車牌極易在卷積特徵圖中徹底湮滅。

為此，我們的兩階段分層設計先嚴格限制搜尋空間：

# 第一階段：先粗定位車輛主體邊界框
vehicle_boxes = detect_vehicles_yolov3(frame, net=vehicle_net, conf_thresh=0.5)

for box in vehicle_boxes:
    x1, y1, x2, y2 = box
    # 裁剪車輛局部候選區域 (Vehicle ROI)
    vehicle_roi = frame[y1:y2, x1:x2]
    
    # 第二階段：僅在車輛局部高解析度區域內檢測車牌
    plate_boxes = plate_model(vehicle_roi)
    for pbox in plate_boxes:
        px1, py1, px2, py2 = pbox
        # 映射恢復至全局絕對座標系
        global_plate_box = [x1 + px1, y1 + py1, x1 + px2, y1 + py2]

2. 突破即時幀率瓶頸：引入 CSRT 目標追蹤器​

深度學習目標檢測模型即便參數量再小，逐幀推論依然會過度擠占計算資源。我們引入了具有空間可靠性圖的 CSRT (Channel and Spatial Reliability Tracking) 濾波追蹤器，採用“間隔檢測 + 逐幀追蹤”的雙核驅動機制：

# 每隔 15 幀執行一次 YOLO 重檢，其餘幀完全交由輕量級 CSRT 追蹤
if frame_count % CONFIG["detection_interval"] == 0:
    boxes = detect_vehicles_yolov3(frame)
    tracker = cv2.TrackerCSRT_create()
    tracker.init(frame, tuple(boxes[0]))
else:
    # 純數學相關濾波快速更新目標框，單幀計算開銷僅需 1~2 毫秒
    success, tracked_box = tracker.update(frame)
    if not success:
        tracker = None

3. 下篇預告​

在接下來的第 4 篇中，我們將深入解決裁剪出的微小車牌解析度過低且受嚴重運動模糊污染的挑戰，探索基於 EDSR_x4 深度超解析度演算法 與 多幀影像疊加降噪 的字元邊緣高保真重建實踐。

📌 核心要點 (Key Takeaways)

• 問題痛點：行車記錄器畫面中普遍充斥著路面積水反光、瀝青修補裂縫、減速帶以及高架橋陰影，極易引發車道線誤檢；簡單的水平/垂直單點座標判斷，無法在車輛變道顛簸時精準界定車輪壓線的物理臨界點。
• 解決方案：設計基於消失點的梯形 ROI 感興趣區域遮罩、雙向斜率絕對值閾值過濾 ($|slope| > 0.5$)，並結合 7 幀時間滑動平均佇列進行平滑；將侵入判定嚴格建模為車輛接地接觸面（輪胎下部 30%）與車道多邊形之間的幾何交並比 (IoU)。
• 落地成效：成功過濾了 95% 以上的路面雜訊，並以亞幀級的時間精度精準捕獲車輛碾壓車道線的瞬間。

1. 動態車道線檢測：Canny 邊緣與機率霍夫變換 (HoughLinesP)​

為了在低清行車記錄器畫面中穩定提取車道線，我們精心調校了基於 OpenCV 的影像前處理管線：

def detect_lanes(frame):
    height, width = frame.shape[:2]
    gray = cv2.cvtColor(frame, cv2.COLOR_BGR2GRAY)
    blur = cv2.GaussianBlur(gray, (5, 5), 0)
    edges = cv2.Canny(blur, 50, 150)
    
    # 建構基於視線消失點的梯形感興趣區域 (ROI)
    mask = np.zeros_like(edges)
    roi_polygon = np.array([[
        (int(width * 0.1), height),
        (int(width * 0.45), int(height * 0.6)),
        (int(width * 0.55), int(height * 0.6)),
        (int(width * 0.9), height)
    ]], np.int32)
    cv2.fillPoly(mask, roi_polygon, 255)
    masked_edges = cv2.bitwise_and(edges, mask)
    
    # 機率霍夫變換擬合直線線段
    lines = cv2.HoughLinesP(
        masked_edges,
        rho=1,
        theta=np.pi / 180,
        threshold=20,
        minLineLength=20,
        maxLineGap=10
    )
    return lines

2. 斜率幾何過濾與多幀時序平滑​

霍夫變換檢出的原始線段往往夾雜橫向路面接縫，我們透過斜率數學約束予以剔除：

直線斜率 m = (y2 - y1) / (x2 - x1)

• 左側車道線候選：m < -0.5（負斜率強約束）
• 右側車道線候選：m > 0.5（正斜率強約束）
• 橫向路面雜音：|m| <= 0.5（斑馬線、減速帶完全剔除）

針對透過初篩的車道線方程式參數，使用 deque(maxlen=7) 的定長雙端佇列維護移動平均值，徹底消除了由於顛簸造成的單幀劇烈晃動。

3. 基於幾何多邊形 IoU 的車道侵入判定​

車輛並非只要車身進入畫面就算侵入，真正的交通違規在於輪胎與標線的物理接觸。我們將車輛接地部分定義為車輛底部 30% 區域（Footprint）：

Footprint = [x_min, y_min + 0.7 * h, x_max, y_max]
IoU = Area(Footprint ∩ Lane_Polygon) / Area(Footprint)

def check_lane_intrusion(vehicle_box, lane_polygon, threshold=0.05):
    vx1, vy1, vx2, vy2 = vehicle_box
    vh = vy2 - vy1
    # 提取車輛物理接地接觸面
    footprint = Polygon([(vx1, vy1 + 0.7*vh), (vx2, vy1 + 0.7*vh), (vx2, vy2), (vx1, vy2)])
    
    # 計算空間多邊形相交重疊面積比
    intersection = footprint.intersection(lane_polygon).area
    iou = intersection / footprint.area
    return iou > threshold, iou

當 IoU > 0.05 時，系統判定發生壓線違規事件，立即啟動下游的 YOLOv5 車牌局部檢測與超解析度重建。

4. 下篇預告​

在第 3 篇中，我們將深入解析 兩階段分層目標檢測架構，展示如何將 YOLOv3 車輛框與精調的 YOLOv5 車牌模型結合，並藉助 CSRT 追蹤器 節省 80% 的 GPU 推論開銷。

📌 核心要點 (Key Takeaways)

• 問題痛點：低解析度行車記錄器畫面普遍存在車身顛簸、逆光高光、運動模糊以及 H.264 編碼失真，使得直接進行車牌文字辨識和車道壓線判定極易發生誤判漏檢。
• 解決方案：設計高度解耦的 6 階段分層電腦視覺架構：Canny/Hough 動態車道線擬合 -> YOLOv3 車輛粗檢 -> 多邊形 IoU 壓線判定 -> YOLOv5 車牌局部精檢 -> EDSR_x4 深度超解析度重建 -> EasyOCR 時序多數表決集成。
• 落地成效：建置了一套純 Python 實作的高吞吐端到端管線，在嚴重劣化的行車記錄器實拍視訊下實作了高強健性的車輛追蹤與車道侵入監控。

1. 專案研發背景：為何車載行車視覺極具挑戰？​

在智慧交通系統 (ITS) 與自動化交通執法場景中，即時車道線侵入檢測與車牌自動辨識 (ANPR) 是核心支柱能力。然而，在真實高速公路與城市道路環境中，行車記錄器實拍視訊面臨著嚴峻的光學與算力挑戰：

1. 極端低解析度與紋理模糊：在前車或超車車輛中，遠距離車牌在整個 640x480 解析度畫面中往往僅佔據 30x15 至 50x25 像素，字元筆畫粘連嚴重。
2. 車身震動與捲簾快門畸變：路面坑洞顛簸、車輛急加速/急減速引發的角度劇烈擺動會導致原本筆直的車道線嚴重扭曲。
3. 即時計算延遲瓶頸：在車載邊緣端逐幀執行龐大的全圖大模型會導致幀率驟降，無法滿足即時視訊串流處理要求。

2. 6 階段分層管線架構設計​

為了兼顧高召回率與即時高吞吐，我們將系統劃分為模組化的 6 階段分工體系：

flowchart TD
    Raw["原始行車記錄器幀 640x480"] --> L1["第1階段：Canny + 霍夫變換動態車道線提取"]
    Raw --> L2["第2階段：YOLOv3-tiny 車輛主體快速粗檢"]
    L1 & L2 --> L3["第3階段：車輛接地接觸面與車道多邊形 IoU 侵入判定"]
    L3 -- 觸發壓線侵入 --> L4["第4階段：車輛 ROI 局部微調 YOLOv5 車牌定位"]
    L4 --> L5["第5階段：EDSR_x4 深度神經網路 4倍超解析度重建"]
    L5 --> L6["第6階段：EasyOCR + 字元正則校驗 + 時序滑動多數表決"]
    L6 --> Result["最終確信違規車牌：64가1511"]

各階段核心職責解耦​

1. 車道提取：基於消失點的梯形動態 ROI 遮罩、Canny 算子與斜率幾何約束，快速隔離出行車走廊邊界。
2. 車輛檢測：輕量級 YOLOv3-tiny 毫秒級輸出畫面內所有候選車輛的外接矩形框。
3. 壓線判定：計算車輛輪胎接地接觸面（底部 30% 區域）與車道邊界多边形之間的幾何交並比（IoU > 0.05）。
4. 車牌定位：微調版 YOLOv5 (lp_det.pt) 僅在發生侵入的車輛局部 ROI 區域內進行推論，大幅縮減無效搜尋面積。
5. 超解析度：將裁剪出的低解析度微小車牌送入 EDSR_x4 深度殘差模型，4 倍高清重建字元邊緣細節。
6. OCR 與表決：EasyOCR 提取字元候選，結合韓國法定車牌語法正則進行初篩，並在 7 幀時間視窗內發起多數表決鎖定最終結果。

3. 核心全域工程參數配置 (CONFIG)​

CONFIG = {
    "output_width": 640,
    "output_height": 480,
    "conf_threshold_vehicle": 0.5,
    "nms_threshold_vehicle": 0.4,
    "min_vehicle_w": 70,
    "min_vehicle_h": 70,
    "lane_iou_threshold": 0.05,
    "detection_interval": 15,
    "min_plate_area_for_ocr": 1200,
    "plate_history_size": 7,
    "plate_confirm_threshold": 3,
    "sr_model": "EDSR_x4.pb",
    "yolo_plate_model": "lp_det.pt"
}

4. 下篇預告​

在接下來的第 2 篇中，我們將深入解析 Canny 邊緣提取演算法、機率霍夫變換數學原理 (HoughLinesP)、斜率幾何異常值剔除 以及核心的幾何多邊形車道侵入判定規則。

June 18, 2026, marks the triumphant completion of the 1st semester of our university capstone engineering project. From our humble beginnings as a simple Android convention scraper in March, Maeumjigi has evolved into a full-scale, clinical-grade AI mental health counseling ecosystem.

Our final sprint focused on two mission-critical objectives:

1. The Dual-Layer Safety Wrapper: Engineering a bulletproof guardrail architecture to guarantee zero-hallucination crisis intervention.
2. Production Cloud Serving & Final Defense: Sizing AWS EC2 GPU infrastructure budgets and delivering our final faculty presentation.

1. The Dual-Layer Safety Wrapper Architecture​

In consumer chatbots, occasional hallucinations or awkward phrasing are minor annoyances. In an AI platform dedicated to youth and military suicide prevention, a single hallucinated response or dismissive answer could be fatal.

To protect vulnerable users, we designed a Dual-Layer Safety Wrapper that wraps around our fine-tuned Qwen 3.5-9B model (Checkpoint-4400):

flowchart TD
    subgraph Inbound_Triage ["Layer 1: Pre-Inference Guardrail"]
        A[User Message Received] --> B[Regex Crisis Keyword Detector]
        B --> C[Zero-Shot Semantic Crisis Classifier]
        C --> D{Risk Severity Assessment}
    end

    subgraph Decision_Branch ["Emergency Routing"]
        D -->|Level 3: Active Suicidality / Imminent Danger| E[Emergency Protocol Triggered]
        E -->|Bypass Generative Model| F[Deterministic Crisis Intervention & 109 / 1393 Dialing]
        
        D -->|Level 1-2: Mild to Moderate Emotional Distress| G[Pass to Fine-Tuned LLM]
    end

    subgraph Inference_Core ["Model Generation"]
        G --> H[vLLM Serving Engine: Checkpoint-4400]
        H --> I[Raw Generative Token Stream]
    end

    subgraph Outbound_Verifier ["Layer 2: Post-Inference Guardrail"]
        I --> J[Toxicity & Hallucination Filter]
        J --> K[Clinical Referral Footer Injection]
        K --> L[Sanitized Real-Time SSE to Client]
    end

    F --> L

Crisis Escalation Protocol (Level 1 to 3)​

2. Guardrail Middleware Implementation​

The Safety Wrapper operates as an asynchronous FastAPI middleware, validating payloads prior to dispatching GPU inference requests:

# Safety Wrapper core logic: safety_wrapper.py
import re
from fastapi import Request, HTTPException

CRISIS_PATTERNS = [
    r"(죽고\s*싶|자살|목숨을\s*끊|살기\s*싫|뛰어내리)",
    r"(suicide|kill\s*myself|end\s*my\s*life)"
]

class SafetyWrapper:
    def __init__(self, emergency_hotline="109"):
        self.compiled_regex = [re.compile(p, re.IGNORECASE) for p in CRISIS_PATTERNS]
        self.hotline = emergency_hotline

    def evaluate_input(self, user_text: str) -> dict:
        for pattern in self.compiled_regex:
            if pattern.search(user_text):
                return {
                    "is_crisis": True,
                    "action": "ESCALATE_IMMEDIATELY",
                    "override_response": (
                        f"당신의 고통을 깊이 공감합니다. 지금 즉시 전문가의 도움을 받으실 수 있습니다. "
                        f"24시간 자살예방 상담전화 ☎ {self.hotline}번으로 연락해 주세요. 당신은 혼자가 아닙니다."
                    )
                }
        return {"is_crisis": False, "action": "PROCEED_TO_LLM"}

3. AWS EC2 GPU Production Budget & Sizing​

To serve our validated chatbot to university students and military beta testers over the 5-month summer break, we conducted an AWS EC2 instance sizing and cost optimization study:

Engineering Selection: While g4dn.2xlarge offered lower cost, its 16GB VRAM could not host our 9B model alongside vLLM PagedAttention KV-caches without extreme 4-bit quantization degradation. We selected g5.2xlarge with a 1-year Savings Plan, unlocking 24GB high-speed GDDR6 VRAM, sub-50ms token latencies, and 37% budgetary savings!

4. 1st Semester Capstone Retrospective & Defense Highlights​

On June 18th, our engineering team presented the completed 1st Semester Final Defense Presentation (PPTX) before the university evaluation panel:

timeline
    title Maeumjigi Semester 1 Engineering Milestones
    March 2026 : Project Kickoff : Claude Code Adoption : Convention Scraper Pivot
    April 2026 : 120K Corpus Preprocessing : Llama 3.1 JSONL Pipeline : Next.js 14 Frontend
    May 2026 : 4 Rounds of Fine-Tuning : Checkpoint-4400 Locked : FastAPI PostgreSQL Hardened
    June 2026 : Dual Safety Wrapper : AWS g5.2xlarge Sizing : 1st Semester Final Presentation Passed

The review panel commended the team for solving the over-counseling trap through empirical data mixing (2:1 ratio) and praised the clinical safety guarantees provided by the deterministic Safety Wrapper.

5. What's Next in Semester 2?​

With Phase 1 concluded, our team enters summer deployment:

1. Provisioning our AWS EC2 g5.2xlarge instance with automated containerized health checks.
2. Launching closed-beta testing across military welfare communities.
3. Returning in Semester 2 with live multi-turn field data and expanded knowledge graph capabilities!

The final week of May 2026 (May 27–30) proved to be the grand culmination of our experimental modeling phase. After weeks of hyperparameter tuning, GPU out-of-memory crashes, and dataset revisions, our 4th Fine-Tuning cycle (fine_tuning_4) crossed the finish line.

This post reveals the technical breakthrough that resolved the chronic "over-counseling" trap, quantitative validation of our golden weight Checkpoint-4400, and the end-to-end system architecture designed for real-world deployment.

1. The Over-Counseling Paradox & Data Mix Optimization​

In our earlier fine-tuning cycles (v1 through v3), the model suffered from an unexpected behavioral pathology we coined the "Over-Counseling Trap":

• When a user said: "Good morning! What should I eat for lunch?"
• The model unnaturally replied: "I hear deep sorrow in your morning greeting. Eating alone can feel overwhelming. Please remember you are not alone; take a deep breath."

Because the training corpus consisted exclusively of 100% clinical depression and psychological counseling transcripts, the model had overfitted into interpreting every casual human interaction as a critical depressive cry for help.

To eliminate this pathological hyper-empathy without compromising crisis intervention sensitivity, we engineered experimental Data Mix Ratios blending daily casual chit-chat (AI Hub Social Multi-Turn Corpus) with our curated counseling data:

pie title "4th Fine-Tuning Golden Mix Composition (2:1 Ratio)"
    "Curated Clinical & Crisis Counseling (AI Hub v4)" : 66.7
    "Open-Domain Daily Chit-Chat & Casual Banter" : 33.3

2. Checkpoint-4400: Loss Convergence & Golden Weights​

We fine-tuned Qwen 2.5 / 3.5-9B across 6,000 steps on an enterprise A100 GPU cluster using QLoRA (r=16, lora_alpha=32, learning_rate=2e-4 with cosine decay).

Analyzing intermediate checkpoints revealed that Checkpoint-4400 represented the exact Pareto-optimal boundary between conversational fluidity and clinical safety:

xychart-beta
    title "Validation Loss & Over-Counseling Metric Across Training Steps"
    x-axis ["Step 1000", "Step 2000", "Step 3000", "Step 4000", "Step 4400", "Step 5000", "Step 6000"]
    y-axis "Validation Loss (Lower is Better)" 0.8 --> 2.4
    line [2.35, 1.82, 1.45, 1.18, 1.04, 1.22, 1.48]

Checkpoint-4400 demonstrated flawless contextual switching: answering casual greetings lightheartedly, while seamlessly transitioning into calm, de-escalating empathy the second emotional vulnerability was detected.

3. End-to-End System Architecture​

With Checkpoint-4400 locked in, we designed the complete production architecture, codified in chatbot_architecture.html:

flowchart TD
    subgraph Client_Tier ["Client Layer (Web & Mobile)"]
        UI1[Next.js 14 Web PWA]
        UI2[React Native Mobile App]
    end

    subgraph Gateway_Tier ["API Gateway & Ingress"]
        Nginx[Nginx Reverse Proxy & SSL Termination]
        FastAPI[FastAPI Asynchronous Gateway]
        Redis[(Redis Session Buffer & Rate Limiter)]
    end

    subgraph Guardrail_Tier ["Safety & Clinical Validation"]
        Guard_In[Pre-Filter: Zero-Shot Suicide & Self-Harm Triage]
        Guard_Out[Post-Verifier: Hallucination & Emergency Hotline Injector]
    end

    subgraph Model_Tier ["Model Serving Infrastructure"]
        vLLM[vLLM High-Throughput Serving Engine]
        Model[(Qwen 3.5-9B + LoRA Checkpoint-4400)]
    end

    subgraph Data_Tier ["Persistence & Analytics"]
        Postgres[(PostgreSQL User & Conversation History)]
    end

    UI1 & UI2 <-->|HTTPS / WSS / SSE| Nginx
    Nginx <--> FastAPI
    FastAPI <--> Redis
    FastAPI --> Guard_In
    Guard_In -->|Passed Safe / Level 1-2| vLLM
    Guard_In -->|Critical Crisis: Level 3| Guard_Out
    vLLM <--> Model
    vLLM --> Guard_Out
    Guard_Out --> FastAPI
    FastAPI <--> Postgres

4. LoRA Adapter Configuration & Automated Reporting​

The finalized adapter_config.json locked our architectural parameters:

{
  "base_model_name_or_path": "Qwen/Qwen2.5-9B-Instruct",
  "lora_alpha": 32,
  "lora_dropout": 0.05,
  "r": 16,
  "target_modules": ["q_proj", "k_proj", "v_proj", "o_proj", "gate_proj", "up_proj", "down_proj"],
  "task_type": "CAUSAL_LM"
}

On May 30th, our autonomous documentation script compiled fine_tuning_4_report.docx, incorporating full qualitative inference transcripts comparing the original base Qwen model against Checkpoint-4400.

5. Day 22 Milestones & What Lies Ahead​

1. Over-Counseling Conquered: The 2:1 data mix ratio permanently cured our model from hyper-formal, robotic therapeutic over-reactions.
2. Golden Weight Staged: Checkpoint-4400 achieved our project's lowest validation perplexity (2.68) and highest human evaluation scores.
3. Production Blueprint Published: Completed the full-stack architecture bridging Next.js, FastAPI, vLLM, and Redis.

In Dev Log #23, we enter the final milestone of Semester 1: building our dual-layer Safety Wrapper guardrail and calculating cloud GPU server budgets for university deployment!

5 月 21 日與 22 日兩天，Maeumjigi 畢業專題團隊全量投入了針對全新高品質語料的大規模批次產生，並正式拉開了第 4 輪微調實驗 (fine_tuning_4) 的帷幕。

擺脫「情緒過敏」：同理心諮商與日常閒聊的博弈​

在嚴密盲測第 3 輪微調模型時，我們捕獲了一個致命缺陷：

「使用純粹心理諮商語料微調後，模型的回覆被嚴重『情緒綁架』。如何才能在保留深層同理心的同時，捍衛模型處理日常對話的自然常識能力？」

我們的核心初衷是打造一位「傳遞溫暖同理心力量的專業心理防範自殺介入導師」。但在全量心理語料過度擬合 (Overfitting) 後，面對使用者諸如「今天天氣如何？」或「午餐吃點什麼？」等毫無負面情緒的日常隨想，大模型依然表現出過度嚴肅、沉重且充滿心理病理化傾向的回應。

為徹底打破這一失衡，我們確立了按科學配比深度混合「情緒介入語料」與「日常百科/閒聊語料」的全新實驗假說。

借助 API 批次處理高效合成 10,000 筆 v6 情緒增強語料​

「參數約束：統一定長 512 Tokens / 單筆平均有效長度 500 Tokens / 涵蓋 20 種典型心理諮商人設 / 持久化目標：v6.jsonl」

為了鍛造最頂級的訓練集，我們呼叫 Anthropic API (Haiku) Batch 批次模式，一口氣合成了整整 10,000 筆長程心理對話資料 (Emotion_train_dataset_v6.jsonl)。中間雖歷經非同步批次無進度回傳的緊張焦慮，但借助補全校驗指令碼 (fill_v6.py) 成功補齊了所有樣本。

探尋黃金分割率：第 4 輪多比例矩陣微調​

「1 萬筆 Emotion_train_dataset_v6 已就緒。請分別按 7:3、2:1 以及 5:5 比例混合日常與情緒語料。」 「本次 fine_tuning_4 擺脫單純調整 LoRA Alpha，轉向以語料混合比例 (mixed_2_1, mixed_5_5, mixed_7_3) 作為核心自變數展開橫向對抗實驗。」

第 4 輪微調自此化身為一場驗證「日常常識」與「專業同理心」能否達成最完美動態平衡的技術競技場。三組異質資料集被注入 Qwen3.5-9B 底座，新一輪 GPU 矩陣訓練轟鳴打響！

📌 核心重點 (TL;DR)

• 問題 (Problem)：微控制器 (Arduino Uno ATmega328P) 僅有 2KB SRAM 的極端算力瓶頸、車輪打滑 (Wheel Slip) 與超音波感測雜訊，以及 Webots 模擬物理與真實硬體之間典型的虛實鴻溝 (Reality Gap)。
• 解決方案 (Solution)：採用分散式 I/O 架構 (HC-06 藍牙, 115,200 baud)，上位機 PC 負責 OpenCV 視覺處理與 Q-Table 決策，Arduino 專注馬達底層 PWM 驅動；搭配俯視攝影機棋盤格去畸變與 ArUco 標記單應性矩陣 (vision.py)，實現次公分級 (x, y, θ) 即時姿態追蹤。
• 實驗結果 (Result)：模擬訓練的 648 狀態 Q 表格零樣本遷移至物理 1.2m × 1.2m 障礙場地中，在無需真實微調的情況下達成了 86.7% 的目標抵達成功率 (26/30 次試驗)，成功跨越虛實鴻溝。

1. Sim-to-Real 的核心挑戰：跨越虛實鴻溝 (Reality Gap)​

在 Webots 模擬環境中，地面摩擦係數恆定，車輪馬達轉速確定，超音波測距亦無雜散反射。然而在真實物理世界中，不可預測的物理擾動無處不在：

1. 算力與記憶體的絕對瓶頸：實體小車主控 Arduino Uno (ATmega328P) 僅具備 32KB Flash 與 2KB SRAM。在晶片上執行深度神經網路或複雜的浮點矩陣運算在物理上是不可能的。
2. 感測器雜訊與反射死角：廉價超音波測距模組在面對壓克力牆面的大角度傾角時，聲波極易發生鏡面散射，導致讀數歸零或突變至最大測量極限。
3. 車輪打滑與累積里程計漂移 (Odometry Drift)：地面摩擦微小差異與左右直流減速馬達的齒輪箱公差，導致即使發出筆直前進指令，小車也會逐漸偏向一側。

2. 分散式控制架構：上位機 PC（大腦）↔ Arduino（肌肉）​

為了打破微控制器的算力限制，我們確立了**「PC 充當大腦，Arduino 充當肌肉」**的分散式控制策略：

flowchart TD
    subgraph CeilingCam["天花板俯視視覺系統 (Ceiling Vision)"]
        Cam["全高畫質網路攝影機 (30 FPS)"]
        Aruco["ArUco 標記偵測 (DICT_4X4_50)<br>單應性矩陣變換 (homography.npy)"]
        Cam --> Aruco
    end

    subgraph PC["上位機 PC (Python 演算法引擎)"]
        Pose["機器人平面姿態估計 (x, y, θ)"]
        Disc["648 狀態離散化模組"]
        QL["已訓練 Q 表格 (ε=0)"]
        BT_Host["HC-06 藍牙序列埠通訊 (115200 baud)"]
        
        Aruco --> Pose --> Disc --> QL --> BT_Host
    end

    subgraph Robot["實體差速移動機器人 (Real Robot)"]
        BT_Slave["HC-06 藍牙從屬模組"]
        MCU["Arduino Uno (韌體)"]
        Motors["L298N 馬達驅動板 + 直流減速馬達"]
        
        BT_Host <-->|"動作位元組指令 [0..3]<br>確認回執/狀態"| BT_Slave --> MCU --> Motors
    end

• 上位機 PC 視覺管線：安裝在天花板上的網路攝影機俯視監控整座競技場，以 30 FPS 的幀率即時偵測小車頂部的 ArUco 二維標記，計算平面絕對姿態 (x, y, θ)，對應進 648 個離散狀態區間，並從 Q 表格中讀取最佳動作。
• HC-06 藍牙通訊最佳化：為了將藍牙序列埠 (SPP) 的往返時延 (RTT) 降至最低，傳輸鮑率由預設的 9,600 提升至 115,200 bps，維持 30~50Hz 的閉迴路控制響應。
• Arduino 韌體 (arduino_firmware.ino)：接收到單一位元組指令（0: 前進, 1: 後退, 2: 左轉, 3: 右轉）後，即刻控制 L298N 驅動晶片輸出精準的脈衝寬度調變 (PWM) 驅動車輪。

3. 俯視攝影機單應性校正與 ArUco 視覺姿態追蹤​

為了在物理場地上實現毫米級精度的姿態解算與障礙測距，我們建置了基於 OpenCV 的俯視電腦視覺管線。

📐 視角校正與單應性變換 (calib_auto.py)​

1. 棋盤格去畸變標定：針對廣角鏡頭的桶形畸變 (Barrel Distortion)，利用標準 9×6 棋盤格提取相機內部參數矩陣 ($K$) 與畸變係數 ($D$) 進行反畸變映射。
2. 透視單應性變換 (Homography)：為了將傾斜的攝影機視角投影為正向俯視的 1.2m × 1.2m 鳥瞰視角 (Bird's-eye View)，透過場地 4 個角落座標擬合出 $3 \times 3$ 單應性矩陣 (homography.npy)。

💻 ArUco 標記姿態解算實作 (vision.py)​

import cv2
import numpy as np

# 載入 ArUco 字典與偵測參數
aruco_dict = cv2.aruco.getPredefinedDictionary(cv2.aruco.DICT_4X4_50)
parameters = cv2.aruco.DetectorParameters()
detector = cv2.aruco.ArucoDetector(aruco_dict, parameters)

def get_robot_pose(frame, homography_matrix):
    """從透視矯正影像中解算機器人的平面座標 (x, y) 與朝向角 (theta)"""
    warped = cv2.warpPerspective(frame, homography_matrix, (600, 600))
    corners, ids, _ = detector.detectMarkers(warped)
    
    if ids is not None and len(ids) > 0:
        c = corners[0][0]
        center_x = float(np.mean(c[:, 0]))
        center_y = float(np.mean(c[:, 1]))
        
        # 利用標記前側邊向量解算朝向角 (theta)
        front_x = (c[0][0] + c[1][0]) / 2.0
        front_y = (c[0][1] + c[1][1]) / 2.0
        theta = np.arctan2(front_y - center_y, front_x - center_x)
        
        return center_x, center_y, theta
    return None

4. 硬體實測避坑排查與真實部署戰報​

在實體小車聯調測試期間，面對突發的硬體邊緣狀況，我們實施了針對性的工程應對方案：

🏆 真實物理場地最終基準測試​

• 自律導航抵達成功率：在物理 1.2m × 1.2m 障礙競技場中展開 30 輪獨立盲測，最終錄得 86.7% 的成功率 (26/30 次成功抵達)。
• 僅依托事先離散化的 2,592 個 Q 表格參數（體積僅約 2.5 KB），小車未經過任何真實環境梯度微調便成功克服了物理摩擦與感測器雜訊。

5. Webots 強化學習系列全篇結語​

至此，歷經 5 篇深度記錄的 Webots 強化學習機器人開發日誌 圓滿收官：

1. #1：648 狀態空間離散化與 Webots TCP Socket IPC 通訊架構
2. #2：表格型 Q-Learning 指數衰減探索與多目標稠密獎勵塑造
3. #3：攻克 12 牆障礙地圖中的局部最佳解與 Headless 自動化模擬
4. #4：evaluate_qlearning 零探索確定性評測及與 DQN、SARSA 的三方基準測試
5. #5：基於 Arduino Uno、藍牙通訊與 ArUco 視覺姿態追蹤的 Sim-to-Real 硬體落地

從虛擬模擬物理建模、演算法核心推導，到大批量多隨機種子自動化測試，最終成功落地於低成本嵌入式實體機器人，本系列完整呈現了機器人強化學習研發的全生命週期。感謝大家的關注與支持，後續敬請期待我們全新的前沿開發實錄！

5 月 19 日至 20 日的兩天時間裡，第三輪微調 (fine_tuning_3) 的評估自動化與面向生產級 App 服務的全端功能深度打磨實作了全面齊頭並進。

第三輪微調收尾：自動化提取最佳 Checkpoint 與平行推論​

汲取前序微調經驗，旨在兼顧知識圖譜確定性規則與自然同理心引導的第三輪微調實驗順利完成訓練：

「自動遍歷 fine_tuning_3 目錄下所有實驗模型，精準篩選 Eval Loss 表現最佳的最佳檢查點 (Best Checkpoint)，替換至對應 adapter 目錄並回報指標。」 「編寫全新的 run_test_20_30.sh 自動化指令碼，在背景針對 fine_tuning_3 展開多卡平行推論與自動評測。」

告別以往繁瑣的人工跨資料夾複製，AI 編寫的高可用指令碼自主提煉最佳權重並配置至推論服務，將 4 組別名候選模型一次性掛在 GPU 伺服器背景展開全自動化基準盲測。

全端貫通：大模型對話 DB 持久化與社群互動功能落地​

在伺服器叢集高速運算的同時，本地全端整合測試也迎來了實質性突破：

「深度梳理 seed_data.sql 初始化認證資訊。預設測試使用者初始密碼究竟是 Test1234! 嗎？當前指令碼目標寫入的目標 DB 架構為何？」

為了徹底殲滅此前導致 401 Unauthorized 鑑權死結的根本誘因，我們逆向審查了資料種子的雜湊散列格式，成功修復了驗證鏈路。

5 月 20 日下午，我們提交了一個里程碑意義的 Git Commit： feat: 챗봇 DB 저장, 게시판 페이지네이션, 감정일기 필터 추가 (支援大模型對話持久化、社群看板分頁及情緒日記多維篩選)

至此，微調大型語言模型的互動上下文終於正式打通資料庫實作了安全落盤儲存！社群看板分頁瀏覽元件以及記錄每日心情起伏的日記多維過濾面板也全部在行動端高品質渲染上線。

無形而龐大的前沿大模型，終於被穩穩裝入了精美的行動應用程式容器之中！

📌 核心重點 (TL;DR)

• 目的 (Objective)：在完全關閉訓練探索雜訊 (ε=0) 的純確定性策略 (Greedy Policy) 下，驗證策略在真實部署環境中的自律導航可靠性與路徑品質。
• 評估方法 (Evaluation)：透過 evaluate_qlearning.py 指令碼，在 5 組獨立測試隨機種子 (Eval Seeds 0~4) 上執行共計 30 輪評估，嚴密監測成功率、理論最短路徑比率 (Path Efficiency) 及接近障礙險情 (Near-miss) 頻次。
• 實驗結果 (Result)：表格型 Q-Learning 在 12 牆障礙地圖中斬獲 93.3% 的確定性抵達成功率，且單步推論延遲僅為 0.02ms，在執行效率與輕量化上顯著優於沉重的深度神經網路 DQN 與保守的在線學習 SARSA。

1. 定量評估管線設計 (evaluate_qlearning.py)​

訓練過程中記錄的獎勵曲線混雜了 ε-貪婪探索的隨機雜訊，無法真實反映即將在實體機器人上執行的確定性貪婪策略 (Deterministic Greedy Policy) 的真實水準。

為此，我們建構了專門的評估引擎，載入訓練保存好的權重檔案 (models/<scenario>/seed_<seed>/qlearning_qtable.npy)，並將探索率嚴格固定為 $\epsilon = 0$：

flowchart LR
    Model["已訓練 Q 表格<br>(qlearning_qtable.npy)"] --> Agent["貪婪代理人<br>(ε = 0 固定)"]
    EvalSeeds["5 組評估隨機種子<br>(EVAL_SEEDS 0..4)"] --> Webots["Webots 模擬器<br>(30 次獨立測試)"]
    Agent <--> Webots
    Webots --> CSV["軌跡與指標記錄<br>(eval_log.csv / traces)"]

💻 核心評估迴圈程式碼​

# evaluate_qlearning.py 核心邏輯摘錄
agent = QLearningAgent(seed=0)
agent.load(model_path) # 載入已訓練的 Q-Table

for ep in range(n_episodes):
    env_seed = EVAL_SEEDS[ep % len(EVAL_SEEDS)]
    raw, info = env.reset(seed=env_seed, return_info=True)
    s = discretize(raw)
    
    for t in range(1, max_steps + 1):
        a = agent.act(s, deterministic=True) # 純粹貪婪決策 argmax Q(s, a)
        raw_next, r, done, info = env.step(a)
        s = discretize(raw_next)
        
        # 記錄軌跡座標與近距擦撞險情 (dist <= 0.15m)
        record_metrics(info)
        if done: break

2. 核心評估指標與度量準則​

除了基礎的「是否抵達目標」之外，我們從平滑度與安全性等多維度進行了深入度量：

1. 抵達成功率 (Success Rate)：在 150 步以內無碰撞且順利進入目標半徑 (0.10m) 範圍的回合比例。
2. 路徑效率 (Path Efficiency)：理論最短幾何距離 (L_shortest) 與機器人實際行駛累積距離 (L_actual) 的百分比比值： Path Efficiency (%) = (Shortest Path / Actual Path) × 100%
3. 近距危險頻次 (Near-Miss Count)：機器人超音波測距與牆體距離低於 0.15m 的危險步數。
4. 振盪與打轉指標 (Oscillation & Spin)：連續左右搖頭抖動與原地無效打轉的步數統計。

3. 三大演算法橫向基準測試：Q-Learning vs. SARSA vs. DQN​

在完全一致的 Webots 12 牆障礙競技場中，對三種經典強化學習演算法展開了對齊測試，揭示了各自的技術權衡：

🔍 演算法行為深度剖析​

• Q-Learning 的優勢：得益於 max_a' Q(s', a') 的離策略特性，Q-Learning 在反向傳播時剔除了探索階段遭遇的隨機碰撞懲罰，能夠精確收斂至最短可行迂迴路徑。
• SARSA 的局限性：由於根據實際取樣的下一步動作更新價值，SARSA 過度畏懼探索期的碰撞，導致策略大幅度繞開牆體，走出過於冗長、效率低下的迂迴航線。
• DQN 的權衡：雖然能精細表達連續狀態，但訓練穩定性高度依賴經驗回放池與目標網路，且 2.15ms 的推論開銷與 GPU 依賴對於 Arduino 等超低功耗微控制器帶來了不可承受的負擔。

4. 定量評估結論​

定量基準測試表明，壓縮至 648 個狀態區間的表格型 Q-Learning 僅憑 2.5 KB 的極小記憶體開銷，不僅在成功率 (93.3%) 上超越了複雜的深度神經網路 (DQN)，更在即時推論吞吐與路徑經濟性上表現優異。

5. 下一步研究方向​

至此，在模擬環境中的全套定量評估已圓滿收官。強化學習最具挑戰性的最終門檻在於向現實物理世界遷移 (Sim-to-Real)。

在最後的第 5 篇中，我們將深入硬體實戰：將訓練好的 Q-Table 部署至 2 輪差速 Arduino Uno 小車，透過 HC-06 藍牙通訊連動，並結合俯視攝影機棋盤格去畸變標定與 ArUco 視覺標記追蹤，揭秘軟硬體聯調與 Sim-to-Real 的關鍵避坑指南！

📌 核心重點 (TL;DR)

• 問題 (Problem)：當目標位於牆體正後方時，由於距離增量獎勵 (+0.1 × Δdist) 固有的貪婪特性，機器人無法主動繞開障礙，而是反覆正面撞牆，深陷嚴重的局部最佳解 (Local Minima) 死結。
• 解決方案 (Solution)：將 3 方向超音波搖頭掃描（前/左/右）狀態感知與長遠視野貝爾曼最佳價值反向傳播 (γ = 0.99) 相結合，並建構基於 PowerShell 的 Webots Headless 無渲染加速管線 (headless_run.ps1)，對種子 0、1、2 進行自動化重複實驗。
• 實驗結果 (Result)：在 12 面牆體障礙環境下，代理人成功習得穩健的側向繞行策略 (Detour Policy)，訓練 600 個回合後目標抵達成功率穩定維持在 90% 以上。

1. 障礙環境面臨的嚴峻挑戰：Local Minima（局部最佳解）陷阱​

在無障礙的開闊競技場 (no_obstacle) 中，代理人只需調整朝向直面目標即可。然而，當在室內場地引入 12 面內建隔斷牆 (obstacle12) 時，獎勵函數的局限性暴露出了致命瓶頸：

flowchart TD
    Start["起點 (Robot)"]
    Wall["牆體障礙 (Wall)"]
    Goal["目標位置 (Goal)"]
    
    Start -->|"直線前進（貪婪距離縮短獎勵）"| Wall
    Wall -.->|"碰撞並陷入停滯 (Local Minima)"| Wall
    Start ==>|"側向繞行策略 (Detour Path)<br>初期承受距離變遠扣分"| Goal

• 直觀困境：當目標位於牆壁正後方時，朝向目標前行將直接誘發牆面碰撞。
• 獎勵衝突與死結：要成功繞過障礙，代理人必須暫時背離目標行駛（導致即時距離增量獎勵為負）。在缺乏充分探索的情況下，貪婪策略拒絕接受即時懲罰，導致機器人在牆前頻繁打轉、不斷發生輕微擦撞或耗盡 150 步逾時上限。

2. 破局之道：搖頭掃描感知與時序差分價值反向傳播​

攻克該局部最佳解陷阱的關鍵在於將 648 狀態空間下的 3 方向測距感知（前方、左側、右側） 與 高折扣因子 (γ = 0.99) 深度結合：

1. 多維度狀態感知：
   • 當機器人處於前方障礙危險 (front_distance = Danger) 時盲目前行，將承受嚴厲的碰撞懲罰 (-1.0)。
   • 若利用伺服馬達搖頭探測到側方開闊通道 (left_distance = Safe 或 right_distance = Safe) 並執行轉向，則可規避撞擊。
2. 長遠時序差分信用分配 (Temporal Difference Credit Assignment)：
   • 儘管側向繞行初期距離目標變遠，但只要最終成功繞過牆壁並命中目標，就能獲得豐厚的正向終止獎勵 (+1.0)。
   • 在 γ = 0.99 的折扣傳播下，終止獎勵沿繞行狀態序列逆向滲透進 Q(s, a) 表格，代理人逐步學會：「在牆壁面前，暫時偏離目標的迂迴路線在長遠預期中能帶來更高累積價值」。

3. Webots Headless 高性能自動化模擬管線​

在複雜的障礙地圖中，為了驗證強化學習演算法的強健性，嚴謹的多隨機種子 (Seeds 0, 1, 2) 交叉驗證必不可少。若每次都在 Webots 桌面圖形介面下手動跑完 3 輪各 1,500 個回合，將耗費數十小時。

我們撰寫了 headless_run.ps1 PowerShell 指令碼，在背景以無渲染高速模式 (--mode=fast --no-rendering) 啟動 Webots，實現全自動無人值守訓練與收斂繪圖：

💻 自動化無渲染管線 (headless_run.ps1)​

# 以高速 Headless 模式背景啟動 Webots
$webotsProc = Start-Process -FilePath $WebotsExe `
    -ArgumentList @("--mode=fast", "--no-rendering", "--stdout", "--stderr", $WorldFile) `
    -PassThru

# 監聽通訊端並啟動強化學習訓練
python train_qlearning.py --scenario obstacle12 --seed 0 --episodes 1500

# 訓練完成後強制清理程序並產生訓練收斂曲線
Stop-Process -Id $webotsProc.Id -Force
python -m qlearning.plot_curves --log-dir logs/obstacle12/seed_0

4. 實證評估：跨環境模擬學習曲線對比​

上圖展示了開闊平原 (no_obstacle) 與 12 牆障礙場地 (obstacle12) 在 3 組獨立隨機種子下的完整學習曲線對比。

📊 核心基準測試指標​

• 探索週期拉長：在 obstacle12 場景下，代理人摸索出可用繞行走廊前碰撞極其頻繁，平均回報在負數區間 (-0.6 ~ -0.4) 持續到了第 400 回合。
• 繞行策略確立：在 800 回合之後，所有隨機種子的成功率均躍升至 90% 以上，證明機器人已牢固掌握在複雜迷宮夾縫中靈活穿行且無碰撞的高級避障策略。

5. 下一步研究方向​

我們成功證明了 648 狀態離散表格型 Q-Learning 能夠應對迷宮級別的複雜障礙繞行。

在第 4 篇中，我們將載入訓練完成的權重檔案 (models/*.npy)，在關閉探索策略的情況下利用 evaluate_qlearning.py 進行確定性測試，並與 DQN 及 SARSA 等經典演算法開展橫向性能對比分析！

📌 核心重點 (TL;DR)

• 問題 (Problem)：在僅於目標抵達 (+1.0) 與牆面碰撞 (-1.0) 時給予反饋的稀疏獎勵 (Sparse Reward) 環境下，代理人往往需要經歷數千個回合的原地打轉或盲目徘徊，才能偶然遭遇目標，探索嚴重延遲。
• 解決方案 (Solution)：設計了結合基於位能的歐氏距離增量獎勵 (+0.1 × Δdist) 與單步 (-0.01)、轉向 (-0.01)、倒車 (-0.05) 懲罰的多目標稠密獎勵塑造 (Dense Reward Shaping) 機制，並搭配指數衰減的 ε-貪婪 (Epsilon-Greedy, 1.0 → 0.05) 探索策略。
• 實驗結果 (Result)：在無障礙 (no_obstacle) 情境下，移動平均獎勵在 500 個回合以內穩健轉正並進入高位區間 (0.7+)，最終導航成功率達到 98% 以上。

1. 表格型 Q-Learning 更新公式與代理人架構​

表格型 Q-Learning (Tabular Q-Learning) 是一種建立在貝爾曼最佳方程式 (Bellman Optimality Equation) 之上的離策略時序差分 (Off-policy Temporal Difference, TD(0)) 演算法。

代理人維護一個形狀為 $(648, 4)$ 的二維 NumPy 陣列作為動作價值表 $Q(s, a)$。利用從 Webots Socket 伺服器即時傳輸的狀態轉移元組 $(s, a, r, s', done)$，代理人依照下列公式即時更新 $Q$ 值：

📐 Q-Learning TD(0) 核心更新公式​

Target = r + γ * max_a' Q(s', a') * (1 - done)
TD Error = Target - Q(s, a)
Q(s, a) <- Q(s, a) + α * TD Error

• 學習率 (Learning Rate, α = 0.1)：平衡吸收全新經驗與保留歷史估計值之間的權重。
• 折扣因子 (Discount Factor, γ = 0.99)：量化未來長期累積回報的現值，對多步導航至關重要。
• 終止狀態遮罩 (1 - done)：在抵達目標或發生碰撞導致回合結束時，將未來的預期價值遮罩為 0，精準提取終止即時獎勵。

💻 代理人核心實作 (qlearning_agent.py)​

import numpy as np

class QLearningAgent:
    def __init__(self, n_states=648, n_actions=4, alpha=0.1, gamma=0.99,
                 eps_start=1.0, eps_min=0.05, eps_decay=0.995, seed=0):
        self.rng = np.random.default_rng(seed)
        self.Q = np.zeros((n_states, n_actions), dtype=np.float64)
        self.alpha = float(alpha)
        self.gamma = float(gamma)
        self.epsilon = float(eps_start)
        self.eps_min = float(eps_min)
        self.eps_decay = float(eps_decay)
        self.n_actions = int(n_actions)

    def act(self, s: int, deterministic: bool = False) -> int:
        """ε-貪婪行為策略：探索與利用的動態權衡"""
        if (not deterministic) and self.rng.random() < self.epsilon:
            return int(self.rng.integers(self.n_actions))
        return int(np.argmax(self.Q[s]))

    def update(self, s: int, a: int, r: float, s_next: int, done: bool) -> float:
        """TD(0) 離策略 Q 表格更新"""
        target = r if done else r + self.gamma * float(np.max(self.Q[s_next]))
        td_error = target - self.Q[s, a]
        self.Q[s, a] += self.alpha * td_error
        return float(td_error)

    def decay_epsilon(self):
        """每個回合結束時執行的指數衰減"""
        self.epsilon = max(self.eps_min, self.epsilon * self.eps_decay)

2. 指數衰減 ε-貪婪探索策略​

在訓練初期，代理人對場地環境毫無先驗知識，必須仰賴 ε = 1.0 (100% 全隨機探索) 來觸碰邊界並發現目標。

然而，若不對探索率進行收斂，即便代理人已經摸索出最佳路徑，仍會因高頻隨機動作而不斷撞牆。為此，我們在每個回合結束時套用逐回合指數衰減公式：

ε_(ep+1) = max(ε_min, ε_ep × 0.995)

• 第 1 回合：ε = 1.0（全方位隨機探索）
• 第 300 回合：ε ≈ 0.22（探索顯著收斂，重心轉向利用高 Q 值經驗）
• 第 600 回合：ε = 0.05（降至設定的最低探索下限 ε_min，保持 95% 確定性最佳利用）

3. 克服稀疏導航獎勵的稠密獎勵塑造機制​

移動機器人導航面臨的核心挑戰是極端稀疏的獎勵反饋 (Sparse Reward Feedback)。在 1.2m × 1.2m 的競技場中，隨機漫遊幾乎無法獲得任何有效反饋，直到偶然撞入 0.10m 的目標容差範圍。

為了有效引導策略收斂，我們在 Webots 控制器 (RL_controller.py) 內部設計了多層稠密獎勵塑造 (Dense Reward Shaping) 體系：

🔍 距離增量 (Distance Delta) 的數學原理​

Δdist = dist_prev - dist_curr

• 朝目標方向前進一步 (0.05m)，立即獲得 +0.1 × 0.05 = +0.005 的即時正向激勵。
• 相反地，若背離目標行駛，則會承受即時扣分。這使得代理人在最初 100 個回合內就能迅速學會將車頭朝向對準目標中心。

4. 實證評估：獎勵曲線與成功率收斂​

在 no_obstacle（無障礙場地）中進行 1,500 個回合的完整訓練，展現了與理論分析高度契合的優異收斂特性。

📈 收斂階段里程碑​

1. 第 0 ~ 200 回合（初期探索階段）：
   • 頻繁發生撞牆以及達到 150 步逾時上限，移動平均獎勵徘徊在負數區間 (-0.4 ~ -0.2)。
2. 第 200 ~ 500 回合（快速攀升階段）：
   • 隨著距離增量位能獎勵在 Q 表格中有效反向傳播，策略在 goal_heading 居中時建立起強烈的直行傾向。
   • 成功率從 20% 迅猛攀升至 80% 以上。
3. 第 500 ~ 1,500 回合（漸近收斂穩定階段）：
   • ε 穩定在 0.05 下限，單回合平均消耗步數從 150 步劇降至 15 ~ 22 步。
   • 100 回合移動平均成功率穩定收斂在 98.5% 以上。

5. 下一步研究方向​

我們已經驗證，在 648 個離散狀態空間下，表格型 Q-Learning 能夠乾淨俐落地征服開闊平原導航。

然而，真實物理世界充滿著複雜的牆面與死胡同障礙。在第 3 篇中，我們將直面 obstacle12 與 obstacle_hard 迷宮地圖，深入剖析代理人如何跳出局部最佳陷阱，並利用多重隨機種子平行訓練建構高強健性導航策略！

Mid-May 2026 was supposed to be a calm interval after wrapping up our 2nd fine-tuning (fine_tuning_2). Instead, May 17th hit our team with a relentless double challenge: condensing hundreds of raw inference metrics into an automated technical report, while simultaneously battling a cryptic HTTP 401 Unauthorized cascading error across our newly integrated FastAPI and PostgreSQL backend.

Here is the complete post-mortem of how we automated our reporting and systematically neutralized the backend authentication breakdown.

1. Autonomous Fine-Tuning Evaluation Reporting​

Analyzing the 2nd fine-tuning results required processing hundreds of inference samples across multiple checkpoint variants (comparing Alpha values: 16, 32, and 64). Doing this manually was mathematically unfeasible given our capstone deadlines.

We engineered a structured prompt document (report_prompt.md) that guided Claude Code to analyze raw JSON evaluation matrices and automatically synthesize an executive technical report:

# Excerpt from report_prompt.md
1. Parse evaluation metrics (BERTScore, ROUGE-L, Perplexity) from /eval/results_alpha_*.json.
2. Group model variants by empathy score, conversational naturalness, and safety compliance.
3. Highlight critical failure cases (e.g., hyper-formal robotic apologies vs conversational warmth).
4. Output the synthesis directly into a publication-ready Word document structure.

The AI agent generated fine_tuning_2_report.docx in under 3 minutes, complete with comparative analysis tables and qualitative excerpt breakdowns.

2. The Nightmare of HTTP 401 Unauthorized in PostgreSQL​

With reporting streamlined, we restored our staging database dump (backup.sql) into a local PostgreSQL instance to test end-to-end user session persistence. Although the database restored with zero SQL syntax errors, our Next.js frontend crashed into an inescapable login loop:

INFO: 127.0.0.1:54322 - "POST /auth/login HTTP/1.1" 401 Unauthorized
DETAIL: {"error": "Invalid credentials or malformed signature"}

Even with verified test credentials (test@maeumjigi.kr / Password123!), the FastAPI authentication service persistently rejected every login handshake.

sequenceDiagram
    autonumber
    actor Client as Next.js Web Client
    participant API as FastAPI Gateway (/auth/login)
    participant DB as PostgreSQL Database
    participant Auth as Passlib Bcrypt Verifier

    Client->>API: POST /auth/login {email, password}
    API->>DB: SELECT id, password_hash FROM users WHERE email=...
    DB-->>API: Returns $2a$12$... hash string
    API->>Auth: bcrypt.verify("Password123!", db_hash)
    Note over Auth: Trap 1: Salt algorithm mismatch ($2a$ vs $2b$)!
    Auth-->>API: Verification Failed (False)
    API-->>Client: 401 Unauthorized

3. Root Cause Investigation & debug_login.py​

To isolate whether the breakdown stemmed from frontend CORS headers, database corruption, or JWT secret misconfigurations, we wrote a standalone diagnostic script: debug_login.py.

# Standalone authentication diagnostic utility: debug_login.py
import sys
from passlib.context import CryptContext
from sqlalchemy import create_engine, text

DATABASE_URL = "postgresql://postgres:secret@localhost:5432/maeumjigi"
pwd_context = CryptContext(schemes=["bcrypt"], deprecated="auto")

def diagnose_user_auth(email: str, raw_pass: str):
    engine = create_engine(DATABASE_URL)
    with engine.connect() as conn:
        result = conn.execute(text("SELECT password_hash FROM users WHERE email = :e"), {"e": email}).fetchone()
        if not result:
            print("[FAIL] User not found in database!")
            return
        
        stored_hash = result[0]
        print(f"[INFO] Retrieved hash: {stored_hash[:15]}...")
        
        # Verify hash algorithm version compatibility
        is_valid = pwd_context.verify(raw_pass, stored_hash)
        print(f"[RESULT] Password Match Status: {is_valid}")

if __name__ == "__main__":
    diagnose_user_auth("test@maeumjigi.kr", "Password123!")

Running this diagnostic exposed three compounding bugs:

, breaking HMAC-SHA256 signature checks. | Sanitized key ingestion: SECRET_KEY = os.getenv("JWT_SECRET").strip().encode('utf-8'). | | **CORS Preflight** | Chrome browser blocked Authorization: Bearerheaders during OPTIONS preflight checks. | Explicitly registeredCORSMiddlewarewithallow_headers=[""]andexpose_headers=[""]`. |

Within 45 minutes of targeted refactoring, login latency dropped to 42ms with a 100% success rate!

4. Architectural Expansion: Exploring Hybrid Knowledge Graphs​

Resolving backend stability opened room for deeper architectural exploration. During clinical evaluation of our 2nd fine-tuned model, we noticed an intrinsic weakness shared by all parametric LLMs: factual hallucinations during multi-hop crisis reasoning.

flowchart TD
    subgraph User_Query ["User Input: Complex Crisis State"]
        U["I stopped taking my SSRI antidepressants 3 days ago and feel severe tremors."]
    end

    subgraph Hybrid_Architecture ["Hybrid Symbolic-Neural Architecture"]
        U --> KG_Extractor[Clinical Entity & Relation Extractor]
        KG_Extractor -->|Cypher Query| KG[(Neo4j Medical Knowledge Graph)]
        KG -->|Verified Triples: SSRI -> Discontinuation Syndrome| Context_Injector[Clinical Context Injector]
        
        U --> Direct_Prompt[Empathetic System Prompt]
        Direct_Prompt & Context_Injector --> FineTuned_LLM[Fine-Tuned Qwen / Llama 3.1]
    end

    subgraph Verified_Output ["Safety-Compliant Response"]
        FineTuned_LLM --> Output["Empathetic validation + Immediate medical warning regarding SSRI discontinuation syndrome."]
    end

By drafting chatbot_design_prompt.md, we laid the theoretical foundation for blending parametric LLM conversational empathy with deterministic Knowledge Graph validation.

5. Day 19 Key Engineering Takeaways​

1. Automated Documentation: Reduced model benchmarking documentation turnaround from 6 hours to under 3 minutes using structured prompts and AI agents.
2. Hardened Authentication: Diagnosed and permanently resolved bcrypt salt mismatches and CORS header traps across PostgreSQL and FastAPI.
3. Hybrid AI Vision: Established the conceptual design for integrating symbolic Knowledge Graphs to eliminate clinical hallucinations in mental health counseling.

In Dev Log #20, we explore the completion of our 3rd fine-tuning cycle and the rollout of live community board features!

📌 核心要點 (Key Takeaways)

• 問題痛點：連續感測器讀數（距離、朝向角）會導致表格型強化學習遭遇維度災難（State-Space Explosion），同時 Python 強化學習代理與 Webots 模擬核心之間需要維持微秒級、低延遲的物理同步。
• 解決方案：設計了基於幾何學空間劃分的 5 維連續感測器量化器（discretizer.py），產生 3 × 8 × 3 × 3 × 3 = 648 維離散狀態；搭建了基於 TCP 5000 連接埠的極輕量級行分隔 JSON 套接字通訊管線。
• 落地成效：實作了 O(1) 複雜度的超高速 Q-Table 定址更新，確保了模擬器與 Python 端 32ms 物理模擬步長的一致無阻塞同步。

1. 專案研發背景：為何選擇 Webots 與經典 Q-Learning？​

讓差速驅動機器人在未知的室內場館中自主導航避障並抵達目標點，是移動機器人學的經典基石課題。儘管深度強化學習（DQN, PPO）在處理高維影像方面表現亮眼，但其龐大的參數量在邊緣微控制器上推論延遲高，且缺乏數學上的完全可解釋性。

在本專欄專案中，我們在 Webots 3D 物理模擬引擎 中應用經典的 表格型 Q-Learning (Off-policy TD(0))，旨在在 1.2m × 1.2m 的室內競技場內訓練出一套數學上完全可驗證的最優避障與導航策略。

2. 系統架構設計：Webots 控制器 ↔ Python 強化學習引擎​

系統解耦為清晰的兩大層級：Webots 模擬端（伺服端） 與 Python 演算法端（客戶端）：

flowchart LR
    subgraph Webots["Webots 3D 模擬器 (localhost:5000)"]
        Robot["Supervisor 機器人<br>(超音波感測器 + 驅動輪)"]
        HeadScan["搖頭掃描機制<br>(左右 1.1 rad 伺服馬達擺動)"]
        Server["TCP Socket 伺服端<br>(行分隔 JSON 協定)"]
        Robot -→ HeadScan -→ Server
    end

    subgraph Python["Python 強化學習引擎 (客戶端)"]
        Env["WebotsEnv (類似 gym 介面)<br>reset() / step()"]
        Disc["離散化映射器<br>(連續感測器 → 0~647 Bin)"]
        Agent["QLearningAgent<br>(Q-Table 形狀 648x4)"]
        Env -→ Disc -→ Agent
    end

    Server <-→|"請求: {type: step, action: 0..3}<br>回應: {state: [...], reward, done}"| Env

• Webots 控制器 (RL_controller.py)：負責執行具體的動作指令 480ms（對應 15 個模擬步長 × 32ms），並驅動機載超音波感測器左右擺動 1.1 rad（約 63°）以消除盲區。
• Socket 協定：採用極度輕量的行分隔 JSON 格式進行 TCP 本地環回通訊：
  • 發送動作請求：{"type": "step", "action": 0} (0: 前進, 1: 後退, 2: 左轉, 3: 右轉)
  • 接收環境回饋：{"state": [0.45, 0.12, 0.35, 0.28, 0.40], "reward": 0.05, "done": false, "info": {...}}

3. 連續感測器讀數的 648 維離散狀態量化​

為了應用表格型強化學習，連續浮點讀數必須被映射至有限離散狀態空間。根據運動學關鍵特徵，我們選取了 5 個核心狀態變數：

總狀態數規模： N_states = 3 × 8 × 3 × 3 × 3 = 648

由此建構的 Q-Table 僅包含 648 × 4 = 2,592 個浮點數條目（記憶體僅佔約 2.5 KB），能在單晶片微秒級定址，徹底擺脫對 GPU 的依賴。

💻 狀態離散化核心程式碼 (discretizer.py)​

import numpy as np

# 5個維度的量化分區基數
N_GOAL_D, N_GOAL_H, N_FRONT, N_LEFT, N_RIGHT = 3, 8, 3, 3, 3
N_STATES = N_GOAL_D * N_GOAL_H * N_FRONT * N_LEFT * N_RIGHT  # 648

_HEADING_BINS = np.linspace(-np.pi, np.pi, 9)[1:-1]
_NEAR_BINS    = np.array([0.15, 0.30])
_DIST_BINS    = np.array([0.6, 1.2])

def discretize(state_dict: dict) -> int:
    """將5元組連續感測器浮點讀數映射至 [0, 647] 之間的1維整數索引。"""
    gd = int(np.digitize(state_dict["goal_distance"], _DIST_BINS))
    gh = int(np.digitize(state_dict["goal_heading"], _HEADING_BINS))
    df = int(np.digitize(state_dict["front_distance"], _NEAR_BINS))
    dl = int(np.digitize(state_dict["left_distance"], _NEAR_BINS))
    dr = int(np.digitize(state_dict["right_distance"], _NEAR_BINS))

    # 計算平鋪的一維索引 (扁平化)
    index = ((((gd * N_GOAL_H + gh) * N_FRONT + df) * N_LEFT + dl) * N_RIGHT + dr)
    return int(index)

4. 伺服馬達搖頭掃描與物理碰撞判定邏輯​

固定的前置單向感測器存在致命的側方盲區。我們實作了主動式的 搖頭掃描機制 (Head-Scan)：

1. 執行動作步：輪子以 3.0 rad/s 驅動 480ms。
2. 頭部旋轉測距：伺服馬達向左擺動 +1.1 rad 採集左側淨空，隨後向右打到 -1.1 rad 採集右側淨空。
3. 回正復位：回位至 0 rad 更新正前方障礙物距離。
4. 終止狀態條件：
   • 抵達目標 (Goal Reached)：與目標點歐氏距離 ≤ 0.10m → 成功 (done = True, 獎勵 $+1.0$)
   • 碰撞發生 (Collision)：任一方向實測距離 ≤ 0.08m → 失敗 (done = True, 懲罰 $-1.0$)

5. 下篇預告​

環境框架、Socket IPC 通訊與 648 維狀態離散化體系已經就位。

在第 2 篇中，我們將深入解析 表格型 Q-Learning 更新公式的數學推導、ε-貪婪指數衰減策略，以及攻克稀疏獎勵難題的稠密獎勵函數設計 (Reward Shaping)！

在徹底修復昨天排查出的別名硬編碼缺陷後，5 月 13 日，我們終於重啟了第二輪微調大模型真實端到端的推論產生能力基準測試。

破除生硬斷裂：放寬產生 Token 長度上限釋放深層同理心​

逐句審讀推論產生的應答文本時，我們發現 Llama33-70B_a8 模型的輸出依然呈現出一種微妙的乾癟與機械緊縮感：

「這是 Llama33-70B_a8 輸出的典型答覆。明顯感覺 max_seq_length 與 max_new_tokens 設得太緊，嚴重束縛了模型表達。結合當前物理顯示記憶體富餘量，極限能上調至多少？」

結合當時約 39.8GB 的空閒 VRAM，我們果斷將最大產生 Token 預算 (max_new_tokens) 調寬至 384。調整帶來的產生質變立竿見影：

[修改前] 「產生這種消極念頭一定讓您備受折磨。及時向專業諮商師求助非常重要。」
[修改後] 「產生這樣的念頭一定讓您獨自承受著巨大的痛苦。但請相信，這絕不代表您內心軟弱，而是身體在向您發出訊號——說明您此刻背負的壓力已經嚴重超載了。我由衷建議您在專業諮商師的陪同下，試著把這些鬱結的情緒一點一點傾訴梳理出來。」

僅僅是鬆綁了產生長度配額，模型便能從容保持長程邏輯一致性，吐露出層層遞進、飽含人情溫度與心理撫慰力量的真摯同理心長句。此前模型之所以三緘其口，純粹是被狹窄的產生長度強行截斷了思路。

LoRA 超參數深度剖析：Alpha 縮放因子對比（a=8 vs. a=16）​

第二輪微調的核心科研目的——驗證 LoRA 縮放因子 alpha 對領域適應能力的影響也迎來了定量結論。 透過深入挖掘 fine_tuning_2 目錄下的收斂日誌，我們繪製出了 05_alpha_comparison_daily.png 等對比折線。在固定 rank=16 的前提下，清晰揭示了 $\alpha=8$（欠擬合防漂移）與 $\alpha=16$（強化領域風格吸收）在訓練後期的損失震盪差異與主觀諮商品質的微妙權衡。

在被賦予合理的超參數與充裕的產生空間後，各大模型終於蛻變出了我們最初構想中那個體貼細膩、專業包容的「心語伴侶」。 中期簡報資料的最終拼圖，在此刻宣告圓滿合攏！