作者: kerwin77106

  • A2A 多代理協議實戰與踩坑筆記

    A2A 多代理協議實戰與踩坑筆記

    📌 本文重點

    • A2A 讓 agents 變成可重用服務,而非每案重寫
    • 協議核心是註冊發現、任務路由與狀態冪等設計
    • 穩定的 A2A 契約可讓框架與部署自由演進

    一旦你有第二個客戶、第二條業務線,原本那套「單體 agent + 一大坨編排器」就會開始失控:每個客戶複製一份 agent 系統、工具無法共享、編排器越寫越巨大。A2A(Agent to Agent)協議的目標就是:用一個標準化通訊協議,把 agent 變成可重用服務,而不是每個專案重造一輪輪子。


    重點說明:A2A 的核心設計

    1. 代理註冊與發現:從「硬編碼 URL」到「可發現的服務」

    單體時代常見寫法:

    // 單體編排器內部硬呼叫
    const result = await routingAgent.handle(request);
    

    一旦你要把同一個 routingAgent 給 N 個客戶用,就需要:

    1. 註冊機制:每個 agent 在啟動時向一個 Registry / Discovery Service 報到:
    2. id:shipment-validator
    3. capabilities:支援的任務類型(schema / tags)
    4. endpoint:如 https://agents.mycorp.com/shipment-validator
    5. 發現機制:編排器不再硬編 URL,而是呼叫 Registry API:
    GET /agents?task=shipment.validate
    

    得到 agent 清單後再去調用具體 endpoint。

    好處:同一組 agent 服務可以給多個客戶編排器共用;換掉實作(LangChain ➝ 自研框架)也只要更新註冊資料。

    💡 關鍵: 透過註冊 / 發現機制,同一個 agent 可被多客戶共用,大幅減少重複實作與維護成本。


    2. 任務路由:編排器既是 server 也是 client

    在多代理場景中,編排器不只是 HTTP server,也必須是 HTTP client:

    • 收到來自外部系統、前端的請求:server 身份
    • 需要委派子任務給其他 agents / 其他編排器:client 身份

    一個最小 A2A 任務請求格式可以長這樣(HTTP + JSON):

    POST /invoke HTTP/1.1
    Content-Type: application/json
    X-Trace-Id: 9f2e0a1c-...
    
    {
      "task": "shipment.validate",
      "input": { "shipmentId": "S123" },
      "context": {
        "tenantId": "customer-a",
        "locale": "zh-TW"
      },
      "caller": {
        "agentId": "orchestrator-logistics",
        "replyUrl": "https://orch-a.mycorp.com/a2a/callback"
      }
    }
    

    返回結果:

    {
      "task": "shipment.validate",
      "status": "success",
      "output": {
        "isValid": true,
        "warnings": []
      },
      "error": null,
      "meta": {
        "traceId": "9f2e0a1c-...",
        "agentId": "shipment-validator",
        "durationMs": 324
      }
    }
    

    關鍵點:

    • task:描述抽象任務,而不是具體路由 URL,方便 routing / 升級
    • caller.replyUrl:允許非同步回調(長耗時任務、跨 VPC 任務)
    • X-Trace-Id + meta.traceId:貫穿多跳 agent 的追蹤

    3. 狀態、錯誤、冪等:分散式 agent 的生存三寶

    多 agent 跨服務邊界後,你必須清楚回答三件事:

    1. 狀態放哪裡?

    2. 不要把 workflow state 塞在 LLM context 裡。

    3. 建議:

      • 長期業務狀態:外部 DB / 狀態機服務(如 Statewright 類型)
      • 短期呼叫狀態:每個 A2A 請求帶 taskRunId,在 DB 以 event-sourcing 或簡單 JSON blob 存歷程。
    4. 錯誤怎麼傳遞?

    {
      "status": "error",
      "error": {
        "type": "VALIDATION_ERROR",
        "message": "Unknown shipmentId S123",
        "retryable": false,
        "details": { "field": "shipmentId" }
      }
    }
    
    • retryable 很重要:編排器根據這個決定是否自動重試或改走 fallback。

    • 冪等怎麼做?

    • 每個任務呼叫帶 requestId:

    {
      "task": "shipment.create",
      "requestId": "create-S123-20240501T100000Z",
      ...
    }
    
    • agent 收到相同 requestId 時,重複回傳同一結果而不是再次寫 DB。
    • 真實踩坑:物流「建立訂單 + 發通知」若沒冪等,在重試時會重複發貨或發兩封簡訊。

    💡 關鍵: 為每個任務設計 requestId + retryable,是避免重複扣款、重複發貨等災難級錯誤的關鍵保險絲。


    實作範例:從單體 Agent app 演進到 A2A 系統

    下面是一個極簡版 A2A 實作,基於 Node.js + Express + HTTP + JSON,示範:

    • agent 如何註冊
    • orchestrator 如何發現 + 呼叫
    • 如何保留 traceId、處理重試

    1. Agent 啟動與註冊

    // agent/shipment-validator.ts
    import express from 'express';
    import fetch from 'node-fetch';
    
    const app = express();
    app.use(express.json());
    
    const AGENT_ID = 'shipment-validator';
    const REGISTRY_URL = process.env.REGISTRY_URL!;
    
    async function register() {
      await fetch(`${REGISTRY_URL}/agents/register`, {
        method: 'POST',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify({
          id: AGENT_ID,
          endpoint: process.env.PUBLIC_URL,
          capabilities: ['shipment.validate'],
          version: '1.0.0'
        })
      });
    }
    
    app.post('/invoke', async (req, res) => {
      const traceId = req.header('X-Trace-Id') || crypto.randomUUID();
      const { task, input, requestId } = req.body;
    
      if (task !== 'shipment.validate') {
        return res.status(400).json({ status: 'error', error: { type: 'UNKNOWN_TASK' }});
      }
    
      // TODO: 查 DB 或外部 API
      const exists = input.shipmentId?.startsWith('S');
    
      res.json({
        task,
        status: 'success',
        output: { isValid: !!exists },
        meta: { traceId, agentId: AGENT_ID }
      });
    });
    
    app.listen(3001, async () => {
      await register();
      console.log('shipment-validator listening on 3001');
    });
    

    2. Registry:最小可用版本

    // registry/index.ts
    import express from 'express';
    const app = express();
    app.use(express.json());
    
    const agents = new Map<string, any>();
    
    app.post('/agents/register', (req, res) => {
      const { id, endpoint, capabilities, version } = req.body;
      agents.set(id, { id, endpoint, capabilities, version });
      res.json({ ok: true });
    });
    
    app.get('/agents', (req, res) => {
      const task = req.query.task as string;
      const matches = [...agents.values()].filter(a =>
        a.capabilities.includes(task)
      );
      res.json(matches);
    });
    
    app.listen(3000, () => console.log('registry on 3000'));
    

    3. Orchestrator:既當 server 又當 client

    // orchestrator/logistics.ts
    import express from 'express';
    import fetch from 'node-fetch';
    
    const app = express();
    app.use(express.json());
    
    const REGISTRY_URL = process.env.REGISTRY_URL!;
    
    async function findAgentForTask(task: string) {
      const res = await fetch(`${REGISTRY_URL}/agents?task=${encodeURIComponent(task)}`);
      const list = await res.json();
      if (!list.length) throw new Error(`No agent for task ${task}`);
      return list[0]; // naive: take first
    }
    
    app.post('/shipment/check', async (req, res) => {
      const traceId = req.header('X-Trace-Id') || crypto.randomUUID();
      const { shipmentId } = req.body;
    
      const agent = await findAgentForTask('shipment.validate');
    
      const requestBody = {
        task: 'shipment.validate',
        requestId: `validate-${shipmentId}`,
        input: { shipmentId },
        context: { tenantId: 'customer-a' },
        caller: {
          agentId: 'orchestrator-logistics',
          replyUrl: null
        }
      };
    
      const resp = await fetch(`${agent.endpoint}/invoke`, {
        method: 'POST',
        headers: {
          'Content-Type': 'application/json',
          'X-Trace-Id': traceId
        },
        body: JSON.stringify(requestBody)
      });
    
      const data = await resp.json();
    
      // 簡化處理,實際上應依 data.status 分支
      res.setHeader('X-Trace-Id', data.meta?.traceId || traceId);
      res.json(data);
    });
    
    app.listen(4000, () => console.log('orchestrator on 4000'));
    

    這樣,你就從原本的「單體 app 內部函式呼叫」,演進到:

    • 多個客戶可以共用 shipment-validator agent
    • 想新增 pricing-agent,只要註冊到 Registry,不改 orchestrator 主程式

    進一步要上 gRPC、使用隊列系統(Kafka / SQS)時,只是把 /invoke 的 transport 換掉,協議 payload 大致可以不變。

    💡 關鍵: 先穩定 JSON 協議,再替換 HTTP、gRPC、Queue 等傳輸層,可以減少大規模重構帶來的風險。


    建議與注意事項:真實踩坑整理

    1. 編排器雙角色帶來的競態條件

    當 orchestrator 既是 server 又是 client 時,常見問題:

    • 同步與非同步混用:一部分任務是同步 HTTP 呼叫,一部分透過 queue 非同步回調,結果狀態管理爆炸。

    建議:

    • 明確區分 請求-回應 vs fire-and-forget 任務 的 API。
    • 在邏輯架構層(可參考 AI Agent Logical Architecture 那篇思路)先畫出 state machine,再實作;工具如 Statewright 類型可以讓流程更可視化。

    2. 訊息格式與 schema 演進

    多客戶、多 agent 之後,改一個欄位就是全網恐慌:

    • 務必使用明確的 version 欄位:
    {
      "protocolVersion": "a2a-1.1",
      "task": "shipment.validate",
      ...
    }
    
    • 新增欄位 ➝ 預設 optional,舊 agent 收到可忽略。
    • 刪除 / 改名欄位 ➝ 用 Deprecation window(先標註 deprecated: true 一段時間)。

    3. 重試與冪等:不要指望下游「應該沒事」

    在多代理系統裡,任何一跳都可能:

    • timeout
    • 500
    • 只執行了一半邏輯

    建議:

    • 所有會造成 side effect 的任務必須有 requestId
    • 在 DB 以 (requestId, task) 做唯一索引
    • 重試時以 requestId 查找舊結果,若存在則直接回傳

    4. 日誌與追蹤:traceId 一定要往外帶

    常見錯誤是只在 API gateway 或第一個 service 打 log。多 agent 下:

    • 每個 A2A 呼叫都要帶 X-Trace-Id header。
    • 每個 agent 回傳結果時,把自己的 agentId、task、durationMs 打到 log。
    • 方便之後在 log system(如 ELK / OpenTelemetry)中串連整條 workflow。

    5. 和 MCP、serverless 編排器整合時的性能與隔離

    • MCP / LangChain / LlamaIndex 等框架:
    • 不要把所有工具都塞進同一個 process;可以把重型工具封裝為獨立 agent,透過 A2A 呼叫,避免單一框架 process 變成巨石。
    • Serverless 編排器(如 Step Functions、Temporal):
    • 用 A2A 把「呼叫 agent」當成一個 task type。
    • 注意冷啟動 + LLM 啟動成本:盡量把 agent 部署為長跑服務,serverless 只負責 orchestration。
    • 隊列系統整合(Kafka / SQS / RabbitMQ):
    • A2A 協議層仍用同一份 JSON schema,只是 transport 從 HTTP 換成 message。
    • 確保 message 中也有 traceId、requestId、task、protocolVersion,否則 debug 會極其痛苦。

    總結:

    • A2A 的本質不是某個框架,而是一套清楚的多代理通訊契約。
    • 一旦協議穩定,你可以自由更換 LLM、agent framework、部署方式,但還能:
    • 在多客戶間重用同一組 agents
    • 控制編排器複雜度
    • 在真實生產環境中可觀測、可回溯、可演進。

    如果你已經有一個「會動但很醜」的單體 agent app,建議先抽出最常用的 1–2 個子任務,照上面的 minimal A2A 協議拆出去,從那裡開始演進,而不是一次重寫全系統。

    🚀 你現在可以做的事

    • 把現有單體 agent app 中 1–2 個常用任務,先按文中 JSON 協議拆成獨立 /invoke 服務
    • 為這些任務統一增加 requestId、X-Trace-Id,並在日誌中打出 agentId、task、durationMs
    • 實作一個最小版 Registry(照文中 registry/index.ts),讓 orchestrator 透過發現機制而不是硬編 URL 呼叫 agents
  • 讓 Notion 變成你的 AI Agent 中樞

    讓 Notion 變成你的 AI Agent 中樞

    📌 本文重點

    • Notion 成為托管多個 AI Agent 的工作台
    • 以狀態變化與欄位更新觸發各種自動化工作流
    • 結合外部 SaaS,打造從資料拉取到 AI 清洗的資料管線

    只要把 Agent 綁在 Notion 頁面和資料庫上,你就能用原本的工作區,托管多個 AI 助手,自動整理內容、跑專案流程、甚至接上外部 SaaS 資料管線。

    參考:Notion 開發者平台介紹(TechCrunch 報導)
    https://techcrunch.com/2026/05/13/notion-just-turned-its-workspace-into-a-hub-for-ai-agents/


    核心功能:Notion 現在是「Agent 工作台」

    💡 關鍵: 把 Agent 綁定在「頁面 / 資料庫」上,等於讓 Notion 變成專屬 AI 助手的工作台,而不是單純筆記工具。

    1. 在頁面 / 資料庫綁定 Agent

    你可以把 Agent 視為「住在某個頁面或資料庫裡的專屬助手」:

    • 每個資料庫都能指定一個或多個 Agent,負責:
    • 自動摘要新頁面內容
    • 解析出行動項(Action items)
    • 幫你填欄位(負責人、優先級、標籤)
    • 每個重要頁面(像 PRD、會議紀錄)可以加上「頁面專屬 Agent」,只處理這一頁的內容與後續追蹤。

    你可以做的事:

    • 為「Meeting Notes」資料庫新增一個 會議整理 Agent,設定規則:只要有新筆記,就產出摘要+行動項目,寫回同一筆紀錄的欄位。

    2. 依「狀態改變」自動執行工作流

    Notion 的資料庫欄位(Status、Select、Checkbox 等)可以變成觸發條件:

    • 例:任務狀態從 Todo → In progress:
    • Agent 自動產生子任務(切分工作)
    • 寫一段「本週進度更新」到更新紀錄欄位
    • 例:狀態改為 Done:
    • Agent 生成 Retro 小結
    • 自動發 Slack 通知給相關頻道

    你可以做的事:

    • 在「專案任務」資料庫加一個 狀態更新 Agent,規則:
    • 當 Status 改成 In progress 時,自動新增 3–5 個子任務欄位建議,讓你選擇採用。

    3. 連接外部 API & 自家服務,變成資料管線

    透過 Notion 開發者平台,你可以把外部 SaaS 當作資料來源,丟進 Notion 再交給 Agent 清洗:

    • 從 CRM(如 HubSpot)、工單系統、回饋表單拉資料進一個「集中資料庫」
    • Agent 負責:
    • 解析文字欄位(工單描述、回饋內容)
    • 自動分類(類別、產品線、嚴重程度)
    • 加標籤或指派負責人

    你可以做的事:

    • 建一個 客戶回饋 資料庫,接上 HubSpot API,讓 Agent 自動幫每則回饋打標籤:功能請求 / Bug / 體驗問題。

    三種實戰場景:從內容、專案到資料管線

    💡 關鍵: 最穩起手式是「先在 Notion 裡把資料結構化」,再讓 Agent 針對欄位與內容運轉,而不是一開始就做複雜自動化。

    1)內容與知識管理:自動整理 PRD、會議紀錄

    典型設定方式:

    1. 建立一個 PRD 資料庫,每個 PRD 是一筆資料。
    2. 為這個資料庫綁定 產品文件 Agent,定義任務:
    3. 讀取 PRD 內容區塊
    4. 生成:
      • 300 字內摘要
      • 主要風險與假設
      • 需要決策的問題清單
    5. 生成內容寫回欄位(Summary / Risks / Decisions)。

    會議紀錄也一樣:

    • Meeting Notes 資料庫 + 會議助手 Agent:
    • 生成摘要
    • 抽取行動項目
    • 自動填入 Owner、Due date 欄位(依你設定的規則或會議參與者)。

    你可以馬上做的事:
    挑一個你最常用的會議紀錄資料庫,新增一個文本欄位 AI 摘要,再設定一個 Agent 規則:新紀錄建立後 1 分鐘內,自動寫入摘要。


    2)專案與工作流:從狀態變化觸發自動化

    想像 Notion = Trello + AI 助手:

    例:產品開發看板

    • 資料庫欄位:Status、Assignee、Priority、更新紀錄 等。
    • 綁定 專案 Agent 規則:
    • 當 Status 從 Design → Dev:Agent 讀整個卡片內容,
      • 自動產出測試清單(Test cases)
      • 寫入 更新紀錄:@QA 並貼測試重點
    • 當 Status → Ready for Release:
      • Agent 產生一段英文 / 中文 release note 草稿
      • 寄出或貼到 Slack 產品頻道。

    你可以馬上做的事:

    • 在專案資料庫加一個 Release note draft 欄位,設定 Agent:只要任務進入 Ready for Release,就根據「變更內容」欄位自動生成初稿。

    3)資料管線:外部工具 → Notion → Agent 清洗

    把 Notion 當成「中間站」:

    範例流程:HubSpot → Notion → AI 標註

    1. 用 Notion developer platform 建立一個簡單整合:
    2. 定期呼叫 HubSpot API 拉新聯絡人 / 回饋
    3. 寫進 Notion Leads 或 Feedback 資料庫
    4. 綁定 銷售線索 Agent 或 回饋分析 Agent:
    5. 解析文字欄位(詢問內容、工單描述)
    6. 填 機會大小、產品類別、優先級 欄位。

    工單系統也類似:

    • 從 Zendesk / Jira Service Management 拉工單進 Notion
    • Agent 自動:
    • 判斷是否為緊急問題
    • 建議指派對象
    • 生出對客戶的回覆草稿。

    你可以馬上做的事:

    • 先選一個來源(如 HubSpot),只同步最小的一個表格(例如最近 50 筆 leads),專心把「自動分類與優先級」這一步做好,再往後串通知或報表。

    怎麼開始:從零到第一個「週報 Agent」

    💡 關鍵: 從一個很小、明確的用例(例如週報)開始,比一次導入整個專案管理更容易落地與調整。

    步驟 1:開啟 Notion 開發者平台權限

    1. 進入工作區 Settings & members。
    2. 在 Integrations / Developers 區塊啟用開發者平台(某些方案需管理員權限)。
    3. 建立一個新 Integration,取得:
    4. Integration ID / Secret
    5. 可存取的資料庫與頁面範圍(務必限制在必要範圍)。

    官方入口:https://www.notion.so/my-integrations (依實際帳號會導向對應頁面)

    行動建議:
    先只開放一個「實驗用」工作區或資料庫給這個 Integration,避免一開始就讓 Agent 看到整個公司內容。


    步驟 2:建立你的第一個 Agent ——「週報助手」

    目標:你在 Notion 填一週做了什麼,Agent 自動:

    • 產出精簡週報
    • 幫你分欄:本週亮點 / 風險 / 下週計畫

    設計方式:

    1. 建立一個 Weekly Report 資料庫,欄位:
    2. Week(日期 / 文字)
    3. Raw notes(你隨便輸入的本週記錄)
    4. Summary(AI 產生)
    5. Highlights、Risks、Next week。
    6. 在開發者平台中,創建一個 週報 Agent:
    7. 觸發條件:Raw notes 更新
    8. 任務:讀取 Raw notes,用固定模板輸出 3 段內容,分別寫入三個欄位。

    你可以馬上做的事:
    找一週你真的很忙的那週,貼入原始 notes(甚至可以是 Slack 摘錄),讓 Agent 幫你整理,看輸出是否能直接拿去給主管或團隊。


    步驟 3:接一個常用 SaaS,從「一句需求」到「實際 automation」

    假設你想要:

    「每天把 HubSpot 新增的高潛力 leads 拉進 Notion,並且自動生成一段聯絡話術。」

    拆成執行步驟:

    1. 自然語言需求 → 規格
    2. 描述給你內部的 AI 或開發同事:
      • 資料來源:HubSpot 新增 leads
      • 條件:lead_score > 80
      • 寫入:Notion Leads 資料庫(Name / Company / Note)
      • Agent 任務:為每一筆產生一段 100 字內的開場訊息。
    3. 實作連接腳本(Node / Python 皆可):
    4. 呼叫 HubSpot API 抓資料
    5. 使用 Notion API 建立資料庫項目
    6. 在 Notion 綁定 銷售話術 Agent:
    7. 觸發:新 lead 建立
    8. 利用 lead 的欄位內容,生成個人化的聯絡訊息,寫入 Opening message 欄位。

    行動建議:
    先把這個流程做成「每天一次批次」而不是即時,方便你人工 review,一兩週成熟後再改成即時自動化。


    與 Zapier / Make 的差別在哪?

    工具類型 名稱 實際核心功能 免費方案 適合誰
    自動化平台 Zapier 連接上百種 SaaS,依事件觸發工作流 有,步數與任務量有限 以「事件轉發」為主的自動化(如表單 → Slack)
    自動化平台 Make 視覺化流程設計、條件分支豐富 有,執行次數有限 複雜條件、自定義 API 整合多
    Agent 中樞 Notion + Agents 在內容上下文中運行 Agent,直接操作頁面 / 資料庫 視方案與工作區設定而定 已把工作放在 Notion,上下文豐富、需要 AI 理解內容的人

    關鍵差異:

    • Zapier / Make:強在「事件與資料欄位」,邏輯清楚但不懂內容。
    • Notion + Agent:強在「內容與上下文」,適合需要理解長文、文件關係的自動化(PRD、會議、工單描述)。

    最實用的做法通常是:

    • 讓 Zapier / Make 負責「資料搬運」
    • 讓 Notion Agent 負責「讀懂內容、整理與生成」。

    安全與權限:啟用前要先想好的事

    在公司導入前,至少做這三件事:

    1. 縮小可見範圍:
    2. 為每個 Agent 建立專用資料庫與頁面,不要一開始就給整個 workspace 權限。
    3. 區分測試與正式環境:
    4. 先在 sandbox workspace 測試 prompt、輸出格式,再搬到正式專案。
    5. 記錄與監控:
    6. 保留 Agent 執行紀錄(可考慮接像 Voker.ai 這類 agent analytics 工具)
    7. 定期 review Agent 產出,調整規則與權限。

    只要你把權限、資料範圍與監控設計好,Notion 就不再只是筆記本,而會變成團隊所有 AI Agent 的中樞:每天在你已經習慣的頁面和資料庫裡,默默跑完一堆你本來要手動做的事。


    🚀 你現在可以做的事

    • 在現有的 Meeting Notes 資料庫新增 AI 摘要 欄位,綁定一個簡單的會議整理 Agent 測試輸出品質
    • 建一個獨立的 Weekly Report 資料庫,實作文中「週報 Agent」流程,實際跑一週看看是否減少整理時間
    • 選一個你常用的 SaaS(如 HubSpot / Zendesk),只同步一小部分資料到 Notion,讓 Agent 做分類與摘要清洗實驗
  • Needle:把工具調用 Agent 塞進手機

    Needle:把工具調用 Agent 塞進手機

    📌 本文重點

    • Needle 是專門負責工具選擇與參數填充的小型中控模型
    • 能在手機級硬體離線、高吞吐運行,降低雲端大模型成本
    • 最適合當工具路由器 / 前置規劃器,輸出穩定 JSON 給其他系統

    Needle 就是一顆專門幫大模型「只負責選工具、組參數、吐 JSON」的超小中控腦,讓工具調用 Agent 能在手機級硬體離線或低延遲運作。

    原始專案在 GitHub:https://github.com/cactus-compute/needle


    核心功能:專心當「工具路由中樞」的 26M 模型

    1. 26M 參數 + 純 Attention:為工具調用瘦身

    Needle 的設計很直接:

    • 只有約 2600 萬參數(26M),比動輒數十億參數的聊天模型小一到兩個數量級。
    • 結構是 Simple Attention Network:只有 attention + gating,沒有 MLP/FFN 層。
    • 目標任務只有一件事:
    • 讀取指令 + 工具列表描述
    • 選擇要用哪個工具(或多個)
    • 從指令中抽出參數
    • 輸出工具調用 JSON

    💡 關鍵: 只有約 2600 萬參數的 Needle,能在極小成本下專門負責工具路由與參數抽取,是取代通用大模型做 function calling 決策的關鍵。

    這代表你的行動步驟是:

    • 如果你現在是用 GPT / Gemini / Claude 來做工具決策(例如 function calling),可以把「決定用什麼工具」這一步改交給 Needle,減少大模型 token 消耗與延遲。

    2. 專門為工具調用預訓與微調

    Needle 的訓練重點不是聊天對話,而是「工具使用」:

    • 先在 200 億 token 上預訓練語言能力。
    • 再用約 20 億條合成函數調用資料微調,來源是模擬 Gemini style 工具(例如鬧鐘、導航、日曆、筆記等)。

    💡 關鍵: 針對 20 億條函數調用資料微調,讓 Needle 在工具選擇與參數解析上比同尺寸聊天模型穩定得多。

    實際上,它不負責長篇推理,而是非常擅長:

    • 從口語指令中抓出結構化欄位(時間、地點、標題…)。
    • 在多個工具之間做正確匹配。
    • 輸出符合 schema 的 JSON 給你直接丟進 API。

    行動建議:

    • 如果你已經有一組工具 schema(例如 OpenAPI、function calling 定義),可以直接拿來給 Needle,讓它幫你產生調用 payload,再由你自己的程式實際發 API。

    3. 手機級硬體也能跑的高吞吐

    作者實測在「消費級裝置」可達:

    • 約 6000 tok/s prefill
    • 約 1200 tok/s decode

    💡 關鍵: 在一般消費級裝置上就能達到 6000 tok/s prefill、1200 tok/s decode,讓 Needle 可以長駐於手機與邊緣設備當本地 Agent 大腦。

    翻成白話:

    • 放在中階手機、平板、開發板(如樹莓派級別 SoC)上,當離線工具路由器是可行的。
    • 可以把 Needle 當作 永遠常駐的本地 Agent 大腦,大模型只在真正需要複雜推理/生成時才被叫起。

    行動建議:

    • 如果你正在做行動 App 或智慧硬體(耳機、車機、家電),可以先用 Laptop 上測試 Needle 的工具選擇邏輯,再評估移植到裝置端做本地推理。

    適合誰用:三種典型場景

    1. 行動裝置上的離線 / 低延遲 Agent

    典型案例:

    • 「早上 7 點幫我叫醒,順便播固定歌單」→ Needle 決定:set_alarm + play_playlist
    • 「開車回家,避開高速公路」→ Needle 決定:navigate,並填好目的地與偏好
    • 「幫我記一條:明天 meeting 要問預算」→ Needle 決定:create_note,抽出時間與內容

    做法:

    • 語音 → 本地 ASR(或雲端 Transcription)
    • 文字指令 + 工具列表 → Needle → 工具 JSON
    • 裝置端程式依 JSON 實際調起鬧鐘、導航、筆記 App

    適合:行動 App 團隊、智慧手錶 / 車機 / AR 眼鏡、想要弱網路或離線也能用的指令助手。

    2. 雲端大模型前面加一層「本地工具路由器」

    你可能遇過這種成本問題:

    • 每個使用者點一個按鈕,就丟完整上下文給 GPT 讓它幫你:
    • 看要不要查資料庫
    • 看要不要 call search API
    • 看要不要調 CRM
    • 結果大部分情況都只是在查一個欄位,卻要跑一整輪大模型推理。

    用 Needle 可以:

    • 由 Needle 先判斷:這次是否需要工具?用哪個?
    • 只有當需要長推理 / 文本生成時,才叫雲端 LLM。

    這樣能直接對應到多代理系統常被提到的「orchestration tax」問題:減少不必要的 LLM orchestration 回合數。

    適合:SaaS 後端、API 產品、任何大量使用 function calling 的服務,希望降成本 + 降延遲。

    3. MCP / Function Calling 之前的一層「前置規劃器」

    如果你已經在用:

    • OpenAI / Gemini / Claude 的 Tool Use / Function Calling
    • 或是某種 MCP(Multi-Channel Prompting 或 Model Context Protocol)架構

    Needle 可以扮演:

    • 用戶輸入 → Needle 選擇:
    • 要走哪一條 MCP channel
    • 要用哪個 Function / Tool
    • 再把整理好的工具調用意圖,交給聊天模型做:
    • 實際回應文案
    • 或進一步分解子任務

    差別在於:

    • 一般微型聊天模型:
    • 會嘗試「理解+回答+決定工具」,但在複雜工具 schema 上容易出錯或 hallucinate。
    • Needle:
    • 不負責聊天,只專注在「選工具+填參數+吐 JSON」。

    適合:已經有多工具、多 Agent 架構的團隊,需要一個可控、可本地跑的規劃器 / 路由器。


    Needle vs 一般微型聊天模型

    名稱 核心功能 免費方案 適合誰
    Needle 工具選擇+參數抽取+輸出 JSON 完全開源,自架 行動 App、硬體端、本地 Agent
    微型聊天模型 閒聊、簡單問答 多數可免費測試 想要基本對話、不重工具調用的人

    關鍵差異:

    • Needle 的輸出預期是結構化工具調用,不是自然語言回答。
    • 在工具 schema 清楚的情況下,Needle 通常比同尺寸聊天模型更穩定地填參數、遵守格式。

    行動建議:

    • 若你只需要「會聊天」:選一般微型聊天模型。
    • 若你需要「穩定地依 schema 呼叫工具」:可以試 Needle 當前置規劃器,再用大模型生成回覆文案。

    怎麼開始:從 clone Repo 到跑出第一個工具調用

    1. 抓下專案與模型

    # 1. clone repo
    git clone https://github.com/cactus-compute/needle.git
    cd needle
    
    # 2. 建議先建立虛擬環境
    python -m venv .venv
    source .venv/bin/activate  # Windows 用 .venv\Scripts\activate
    
    # 3. 安裝依賴
    pip install -r requirements.txt
    

    模型本體會在首次推理時自動下載(或依 README 指示手動下載權重)。

    2. 用現成推理腳本跑官方 demo

    Repo 裡提供了簡單的推理範例(實際檔名可能隨版本變動,可在 examples/ 或 README 中找到):

    python examples/simple_tool_calling.py
    

    通常你需要提供:

    • 工具 schema(JSON / Python dict)
    • 使用者指令文字

    腳本會回傳一段包含工具名稱與參數的 JSON,確認能跑通是第一步。

    行動建議:

    • 先照官方 demo 跑一遍,不改任何 schema,只看 Needle 如何選工具。

    3. 定義自己的工具 schema

    假設你要做一個簡單的鬧鐘 + 記事 Agent,可以這樣定義工具(示意):

    tools = [
      {
        "name": "set_alarm",
        "description": "設定鬧鐘時間(24 小時制)",
        "parameters": {
          "type": "object",
          "properties": {
            "time": {"type": "string", "description": "例如 07:30"},
            "label": {"type": "string", "description": "鬧鐘備註"}
          },
          "required": ["time"]
        }
      },
      {
        "name": "create_note",
        "description": "建立一則文字筆記",
        "parameters": {
          "type": "object",
          "properties": {
            "title": {"type": "string"},
            "content": {"type": "string"}
          },
          "required": ["content"]
        }
      }
    ]
    

    接著丟給 Needle:

    from needle import NeedleModel
    
    model = NeedleModel.from_pretrained("cactus/needle-base")
    
    user_query = "明天早上七點叫我起床,順便幫我記:早會要問預算"
    
    result = model.route_tools(query=user_query, tools=tools)
    print(result)
    

    預期會拿到類似:

    [
      {
        "tool": "set_alarm",
        "arguments": {"time": "07:00", "label": "早會"}
      },
      {
        "tool": "create_note",
        "arguments": {"title": "早會", "content": "早會要問預算"}
      }
    ]
    

    接下來只要用你熟悉的語言(Swift / Kotlin / Node / Python),依這個 JSON 實際呼叫 OS API 或雲端 API 即可。

    4. 把 Needle 接在現有 LLM 後面,做一條簡單 workflow

    以下是一條最小可行的 workflow(伪碼):

    1. 語音 → 文字
    2. 行動裝置用本地或雲端 ASR:
    3. speech.wav -> transcript = "幫我找台北明天不下雨的戶外咖啡廳"

    4. Needle 選工具

    5. 工具例:search_weather, search_places 兩個 API。
    6. needle.route_tools(transcript, tools) → 回傳要先查天氣再查地點的參數 JSON。

    7. 實際 API 呼叫

    8. 你的後端或 App 依 Needle 給的 JSON,分別呼叫天氣 API、地點 API,整理出可用候選。

    9. 大模型生成回覆(可選)

    10. 把 API 結果 + 原始指令送給 GPT / Gemini / Claude,只讓它負責自然語言回覆:「幫你找到三間明天不預測下雨的咖啡廳…」。

    這種分工方式:

    • Needle:做工具決策+參數解析
    • LLM:只在真正需要「說人話」的最後一步出現

    能同時達到:成本可控、延遲更低、邊緣裝置也能預先處理大量決策。


    適合誰現在就試用 Needle?

    • 行動 App 開發者:想做語音指令、快捷操作、離線助手,又不想每次都打雲端 LLM。
    • 硬體產品團隊:智慧手錶、車機、家電、AR 眼鏡,需要一顆小而穩定的本地「工具路由中樞」。
    • 個人自架 Agent 系統玩家:已經有多工具、多 Agent,正在煩惱 orchestration 成本和延遲的人。

    只要你場景的核心在「選工具+填參數」,而不是長篇聊天,Needle 值得你花一個下午跑起 demo,直接把它塞到你的 workflow 裡測一次。更多細節與最新腳本可以在 GitHub 查看:https://github.com/cactus-compute/needle

    🚀 你現在可以做的事

    • 先 clone Needle 專案並跑一次官方 demo:git clone https://github.com/cactus-compute/needle.git
    • 把你現有的 function calling / OpenAPI schema 丟給 Needle,觀察它產生的工具 JSON
    • 在一個實際專案裡,嘗試用 Needle 接在 ASR 和雲端 LLM 之間,實測延遲與成本差異
  • AI 寫零日攻擊碼,還把它當玩具嗎?

    AI 寫零日攻擊碼,還把它當玩具嗎?

    📌 本文重點

    • AI 已讓零日攻擊與供應鏈攻擊走向自動化與規模化
    • 90 天修補窗口已失效,防禦必須用 AI 對齊攻擊速度
    • 安全 AI agent 應成為企業級基礎設施而非玩具

    AI 驅動的網路攻擊已經不是「未來風險」,而是正在發生的「既成事實」。如果你還只把 LLM 當作寫文件、產生 demo 的小幫手,而不是下一代攻防基礎設施,你的團隊其實已經在下一波網路戰裡,排隊等著當靶子。接下來幾年,真正的分水嶺不在「有沒有用 AI」,而在於:你的安全體系,有沒有讓 AI 上場。


    一、Google 零日 + TanStack + 30 分鐘 exploit:攻擊工具鏈已經「自動化 + 規模化」

    Google Threat Intelligence Group 最近公開的報告,是個象徵性時刻:首次高信心確認,一個零日攻擊 exploit 是在 AI 協助下開發出來的。

    • 攻擊目標:未具名的開源網頁系統管理工具
    • 風險:可繞過雙重驗證,用來發動「mass exploitation event」
    • 技術線索:程式碼中出現虛構的 CVSS 分數、結構化、教科書式範例風格——典型 LLM 生成痕跡

    這不是「AI 幫忙補幾行程式」而已,而是:

    • 利用 LLM 做漏洞探測、變體生成、payload 組合
    • 形成半自動化的攻擊流水線,可以一次掃遍大量開源專案與雲端服務

    同一週,你在 TanStack npm 供應鏈攻擊 的復盤裡會看到另一個關鍵訊號:

    • 攻擊者利用發布流程和信任鏈,讓自我擴散的 npm 蠕蟲,把 release automation 直接變成惡意程式散佈系統
    • 當這套流程加上 LLM,自動改寫、混淆、適配不同目標環境,每次發版就成了一次攻擊波

    再疊加 The Decoder 報導的數字:

    AI 可以在 30 分鐘內,把一個公開的 patch 反向工程成可行 exploit,而不是過去假設的「90 天披露視窗」。

    💡 關鍵: 從「30 分鐘出 exploit」到「90 天修補窗口」的落差,代表傳統修補節奏在 AI 攻擊面前已完全失效。

    這三件事合在一起,代表什麼?

    1. 零日不再稀缺:有 AI 的攻擊者,可以把「找洞」當日常背景任務跑,用 agent 不停 fuzz 各種系統、協定、套件。
    2. 武器化速度指數級加快:從 commit 出現的那一刻起,計時單位不再是天或週,而是分鐘。
    3. 攻擊開始「工業化」:Google 已經點名,中國、北韓、俄羅斯國家級行為者都在用 AI 生成與隱匿惡意程式碼,這不是 hobby hacker,用的是有預算、有治理的工具鏈。

    產業如果還把 LLM 當成「寫 spec 的 intern」,是在對著一支已經 AI 武裝完畢的對手,光著身體上戰場。


    二、從維護者到 CISO:你以前以為可接受的風險,現在都不夠看

    1. 開源維護者:依賴樹掃不完,攻擊者卻有無限 agent

    TanStack 事件暴露一個殘酷現實:

    • 主流 JS 專案動輒上千個 transitive dependencies
    • 真正有時間逐一審查的維護者幾乎不存在

    過去你的對手也很累,要人工手動挑戰目標。現在不一樣:

    • 攻擊者可以丟給 AI 批次閱讀 release note、commit 訊息、CHANGELOG,自動標記「可能含安全修補」的版本
    • 再用 AI 自動生成 PoC,掃遍整個 npm / PyPI / Maven 生態

    結果就是:

    • 你沒時間看完的依賴樹,攻擊者有 AI 幫他看完
    • 你的評估節奏如果還停留在「每季安全 review」,就是把整季的暴露面,打開給自動化掃描器

    💡 關鍵: 人類難以處理的巨量依賴與變更閱讀,正好是 AI 的強項,攻擊者已經在用這個不對稱優勢。

    2. 企業 CISO:90 天修補視窗已經被 AI 毀掉

    傳統漏洞披露規範喜歡談 90 天修補窗口。但在「patch 30 分鐘變 exploit」的世界:

    • 補丁 push 上去的當下,防守方與攻擊方看到的是同一份 diff
    • 唯一差別是:攻擊者更有誘因、也更願意砸算力,用 AI 把它變現

    這對 CISO 有幾個直接含義:

    1. 風險時間軸縮到「小時計」:安全例會開完、變更流程簽完,攻擊都已經上線。
    2. 「先修內部、再等 90 天公告」的策略破產:只要你還在灰度 rollout,互聯網上就已經有人在 fuzz 同一個 patch。
    3. 資安預算結構要調整:花錢在更多「人力審查」已經不是解法,你需要的是能跟 AI 攻擊速度對齊的 AI 防禦。

    如果 CISO 還用「年度計畫」思維看待這件事,本質上就是把防守節奏鎖死在上一個時代。

    3. SaaS 團隊:單一 LLM 當機 = 關鍵系統直接斷電

    另一個被低估的風險,是把 LLM 當成黑盒 SaaS 依賴的系統性脆弱性。

    Towards AI《The Silicon Protocol》 模擬的 2025/6/10 OpenAI 15 小時 outage,其實已經很接近現實:

    • 340 家醫院的臨床 AI 系統同時癱瘓
    • 緊急分診時間從 18 分鐘飆到 47 分鐘
    • 影響 12,000+ 醫師、48 萬次病患互動
    • 金融交易、政府補助審核一併停擺

    💡 關鍵: 當單一 LLM 供應商成為醫療與金融等關鍵系統的單點故障時,穩定性就等同於安全性。

    這個故事的重點不是「OpenAI 不穩」,而是:

    • 你把 LLM 當成核心業務邏輯的一部分,卻沒有任何真正的容錯策略
    • 一個 API 掛掉,就讓醫療、金融、政務整條鏈路被 AI 單點故障拖下水

    在 AI 武器競賽裡,穩定性本身就是安全性的一部分。你不能一邊擔心對手用 AI 來打你,一邊又把自己的生命線綁在單一 AI 供應商上。


    三、把「安全 AI agent」當基礎建設,而不是玩具

    如果攻擊和防禦都勢必 AI 化,那當務之急不是「要不要用 AI」,而是你要先讓哪一邊 AI 化。

    我的具體主張是:企業應該把安全 AI agent 視為和 CI/CD、觀察性平台同等級的必備基礎設施,而不是創新實驗室的 side project。

    具體來說,有三個落地方向:

    1. 把防禦型 agent 綁進 CI/CD pipeline

    參考 OpenAI Daybreak、Claude Mythos 這類防禦型 agent 的思路:

    • 在 PR / merge 前,強制跑一層「AI secure code review」,針對認證、權限邊界、注入、序列化等高風險區塊給出阻擋級建議
    • 新的依賴被加入時,agent 自動:
    • 解析其 transitive dependencies
    • 對 changelog / issue / CVE 記錄做語意掃描
    • 給出「風險評級 + 建議替代方案」

    這不是「多一個便利工具」,而是把人類不擅長的大規模重複閱讀工作,直接交給 AI。

    2. 在營運監控中佈署「紅隊風格 agent」

    你遲早會遇到 AI 驅動的紅隊,最好是先有自己的:

    • 持續對你的外部攻擊面(域名、API、開放服務)進行自動化攻擊模擬
    • 定期嘗試利用已知 CVE、misconfig、過期依賴,並把結果饋入風險儀表板

    關鍵是 mindset:不要等真實攻擊者幫你做滲透測試。你的 AI agent 應該比對手先一步找到同樣的洞。

    3. 把「AI 依賴治理」寫進公司級規範

    最後,是治理與預算層面要跟上:「攻擊與防禦都會 AI 化」應該變成董事會與監管對話中的顯性假設:

    • 制定 LLM 依賴政策:
    • 不得只有單一 LLM 供應商
    • 必須有降級路徑(rule-based fallback、第二供應商、離線模型)
    • 資安與平台預算中,要明確列出AI 防禦基建項目,而不是把它擠在「創新實驗」下面
    • 對外回應監管機構時,直接承認:沒有 AI 的防禦是落後的防禦,並說清楚你的 AI 控制措施(資料隔離、權限、審計)

    給開發者與團隊的結論:先決定你要站在哪一邊的時間線上

    AI 已經在幫人寫零日攻擊碼、在 30 分鐘內把 patch 變 exploit、把供應鏈攻擊規模化。這不是「會不會發生」的問題,而是「你要在它普及前還是普及後,才開始防守」的問題。

    對開發者與團隊,我的具體建議是:

    1. 今年就把一個防禦型 AI agent 接進 CI/CD,哪怕只先做 code review 和依賴分析。
    2. 把你的 LLM 依賴畫成圖,問自己:這個點掛掉,哪些服務會立即停擺?沒有備援,就安排 roadmap 做。
    3. 在下一輪預算或 OKR 設定時,明文提出「AI 強化安全」而不是「AI 生產力實驗」,讓安全團隊主動擁有這支工具。

    在 AI 資安武器競賽裡,你沒有選擇「要不要參戰」的權利,只有「要不要還用人力跑步去追一輛裝了渦輪的卡車」。趕快讓自己的防禦體系,也裝上 AI 引擎。現在開始,還來得及。

    🚀 你現在可以做的事

    • 在現有 CI/CD pipeline 中接入至少一個防禦型 AI agent,先從程式碼與依賴安全檢查開始
    • 畫出團隊對各家 LLM 的依賴拓樸圖,標記單點故障並規劃第二供應商或離線備援
    • 在下一次年度規劃或 OKR 會議中,把「AI 強化安全」列為獨立目標,由安全或平台團隊負責落地
  • RL 訓練版 Prompt Cache 7.5x 提速解析

    RL 訓練版 Prompt Cache 7.5x 提速解析

    📌 本文重點

    • 長 prompt / 短 response RL 訓練會浪費 >90% 計算
    • 把推理用 KV/prefix cache 思路搬進帶梯度訓練可大幅提速
    • 在 Qwen3.5-4B 上實測最高約 7.5x throughput 提升

    長 prompt、短 response 的 RLHF/RLAIF 任務(例如對話評分、工具調用評分)有一個非常痛的點:每個樣本都在重算同一段 prompt。對 1000-token prompt、100-token response 的場景,你實際上有 >90% 的 FLOPs 在白白重褾。這篇要講的是:如何把推理時的 KV/prefix cache 思路搬進帶梯度的 RL 訓練,在 Qwen3.5-4B 上實測最高拿到 7.5x 速度提升,並給你一套可以直接落地的工程實作方案。

    💡 關鍵: 在長 prompt / 短 response 場景中,重用 prompt 前向計算可將大部分重複 FLOPs 直接省掉,帶來數倍級 throughput 提升。


    重點說明

    1. 為什麼 RL 訓練會浪費那麼多計算?

    典型的 RLHF/RLAIF 術次資料形態:

    • prompt:系統 + 多輪對話 + 任務描述(幾百到上千 tokens)
    • response:模型生成或候選回答(幾十到一兩百 tokens)

    多數開源 RL engine(包括許多自寫 pipeline)會:

    [ prompt tokens ][ response tokens ]
      T_prompt           T_resp
    

    對每一個樣本、每一次 rollout / gradient step,都從頭跑整條序列,雖然 prompt 完全相同,只是 response 不同。這會帶來幾個直接影響:

    1. GPU 利用率被長 prompt 綁死:
    2. 你以為自己 batch size 是 64,其實「有效」只有在 response 段,前面 90% 的計算是在重放。
    3. batch 設計被 context 長度限制:
    4. 1000+ token prompt 會吃掉大部份 memory,導致你無法疊大 batch,只能靠 gradient accumulation,進一步增加 step latency。
    5. RL 特有放大器:
    6. 同一個 prompt 下可能要算多個候選 response、policy/value 多頭、不同 reward function,全都從 prompt 重新 forward 一次。

    因此,只要你是「長 prompt / 短 response」型任務,任何一點在 prompt 端節省的 FLOPs,都是純利潤。


    2. 把 KV/prefix cache 搬進訓練:核心思路

    推理時我們早就習慣用 KV cache/prefix cache:

    1. 先跑一次 prompt,存下每層的 key/value(或 hidden states)。
    2. 生成 response 時,只計算增量 token,復用前綴。

    在訓練中要做到類似的事情,難點在於:

    • 我們需要 完整的 computation graph(for backprop)。
    • 不能只存數值(像推理那樣),還要讓 autograd 知道這些值是可導的。
    • 不能打壞 attention:response 的 attention 要能看見 prompt token 的 hidden states。

    一種工程上可行的做法(簡化描述):

    1. 把序列拆成兩段圖:prompt graph + response graph。
    2. prompt 部分:
    3. 前向一次,拿到 prompt hidden states(例如每層的 h_prompt)與最後一層的 cache-like 表示。
    4. 保留其 computation graph(不 detach),但不馬上 backward。
    5. response 部分:
    6. 再跑一次 LLM,但將 prompt 當成固定 prefix 傳入,使 response token 的 attention 能看到這些 prefix hidden states。
    7. 在 PyTorch 裡可以透過自訂 forward 函數,把 prompt hidden states 塞回 attention 模組,類似手動實作 prefix cache。
    8. loss 計算只對 response tokens 做(例如 policy loss、value loss),但梯度會沿著 response→prompt 的 graph 反傳,保證不破壞訓練正確性。

    關鍵是:

    • 只對 prompt 前向一次,但仍然讓 prompt 參與梯度更新。
    • 對同一 prompt 的多個 response,重複使用一份 prompt hidden states(甚至在一個批次中共享)。

    在 Qwen3.5-4B 上,reddit 實測:

    • prompt : response ≈ 10:1(例如 1000:100)
    • RL 任務:長對話 + 短完成
    • 快取後在長 prompt/短 response 工作負載下 最高取得 ~7.5x step throughput 提升(取決於實際長度比與 IO/通信開銷)。

    💡 關鍵: 當 prompt 與 response 長度比約 10:1 時,只重算 response 部分可在實測中帶來約 7.5 倍 step throughput 提升。


    3. 什麼任務最吃紅利?

    根據 Qwen3.5-4B 測試經驗與工作負載特性,大致可以這樣判斷:

    1. 長 prompt / 短 response(T_prompt / T_resp ≥ 4)
    2. 如:對話 RLHF 評分(用戶上下文很長,模型答覆很短)。
    3. 工具調用評分:所有工具 schema + log 作為 prompt,再對短 decision 進行 RL。
    4. 部分代碼 RL:整個大檔案為 prompt,模型只改一小段。
    5. 這類場景通常可以拿到 3x–7.5x 的實際提速。

    6. 中 prompt / 中 response(T_prompt / T_resp ≈ 1)

    7. 如:通用問答 RLHF(prompt 只有一兩句,回答較長)。
    8. 提速有限,約 1.2x–2x,且實作複雜度可能不值。

    9. 短 prompt / 長 response(T_prompt / T_resp < 1)

    10. 基本沒紅利,甚至會因複雜控制流、多段 graph 而變慢。

    實務上可以用一條 thumb rule:

    如果你平均的 prompt token 數是 response 的 3 倍以上,就應該認真評估導入。

    💡 關鍵: 當 T_prompt 至少約為 T_resp 的 3 倍時,引入訓練版 prompt cache 通常才有顯著性價比。


    實作範例

    以下示例是 PyTorch 為主,偏 pseudo code,但結構與實務工程接近。

    1. 資料結構與 DataLoader 改寫

    我們先把一個 RL batch 明確拆成 prompt / response:

    # 每個樣本:
    # prompt_ids: [T_p]
    # resp_ids:   [T_r]
    
    class RLDataset(torch.utils.data.Dataset):
        def __getitem__(self, idx):
            item = self.data[idx]
            return {
                "prompt_ids": item.prompt_ids,   # 長
                "resp_ids": item.resp_ids,       # 短
                "reward": item.reward,           # 或 advantage
            }
    
    
    def collate_fn(batch):
        # padding & batch 組合
        prompt_ids = pad_sequence([b["prompt_ids"] for b in batch], batch_first=True)
        resp_ids   = pad_sequence([b["resp_ids"]   for b in batch], batch_first=True)
    
        # 生成對應 mask
        prompt_attn_mask = (prompt_ids != pad_token_id)
        resp_attn_mask   = (resp_ids   != pad_token_id)
    
        return {
            "prompt_ids": prompt_ids,
            "resp_ids": resp_ids,
            "prompt_mask": prompt_attn_mask,
            "resp_mask": resp_attn_mask,
            "reward": torch.tensor([b["reward"] for b in batch]),
        }
    

    2. 模型 forward:拆成 prompt graph + response graph

    假設你有一個可插拔的 LLM 模型 model,我們新增兩個關鍵 API:

    • model.forward_prompt(...):只跑 prompt,返回 hidden states(及必要 cache)。
    • model.forward_response_with_prefix(...):給定 prefix hidden states,跑 response。
    class RLPromptCacheModel(nn.Module):
        def forward_prompt(self, input_ids, attention_mask):
            # 返回每層的 hidden,或最後一層即可
            # 重要:不要 detach,保持 grad
            outputs = self.transformer(
                input_ids=input_ids,
                attention_mask=attention_mask,
                output_hidden_states=True,
            )
            return outputs.hidden_states  # list[Layer][B, T_p, H]
    
        def forward_response_with_prefix(self,
                                         resp_ids,
                                         resp_mask,
                                         prompt_hidden_states,
                                         prompt_mask):
            # 這裡需要改造 attention:
            # 讓每層 self-attention 的 KV = [prompt, resp]
            # 可以在每層 module 裡寫一個 hook,或實作 custom attn。
            outputs = self.transformer_with_prefix(
                resp_ids=resp_ids,
                resp_mask=resp_mask,
                prefix_hidden_states=prompt_hidden_states,
                prefix_mask=prompt_mask,
            )
            return outputs.last_hidden_state
    

    核心點:transformer_with_prefix 要做到:

    • 對於每層的 self-attention:
    • query 來自 response tokens;
    • key/value 為 [prefix_hidden_states; resp_hidden];
    • 這讓 response token 能正常 attend 到 prompt,並保持完整 graph。

    實務上可以參考 FlashAttention / prefix-tuning 的實作方式,直接拼接 prefix hidden 作為額外 token,再控制 mask:

    def transformer_with_prefix(...):
        # 假設我們把 prefix & response 在 time 維度上串起來
        # 注意這裡是邏輯串接,實際可用 concat + mask 控制
        concat_hidden = torch.cat([prefix_hidden, resp_emb], dim=1)  # [B, T_p+T_r, H]
        concat_mask   = torch.cat([prefix_mask, resp_mask], dim=1)   # [B, T_p+T_r]
    
        # 交給原本的 transformer 做 self-attention
        outputs = self.base_transformer(
            hidden_states=concat_hidden,
            attention_mask=concat_mask,
        )
        # 只取 response 對應位置的輸出
        resp_hidden_out = outputs.last_hidden_state[:, -resp_len:, :]
        return resp_hidden_out
    

    3. Loss 計算與 RL head

    以 policy gradient 為例,我們只對 response token 做 loss:

    prompt_hs = model.forward_prompt(batch["prompt_ids"], batch["prompt_mask"])  # list[L]
    
    resp_logits = model.forward_response_with_prefix(
        batch["resp_ids"],
        batch["resp_mask"],
        prompt_hs,
        batch["prompt_mask"],
    )
    
    # policy head
    logits = policy_head(resp_logits)  # [B, T_r, V]
    log_probs = F.log_softmax(logits, dim=-1)
    
    # 只對實際採樣到的 token 做 loss
    # 假設 resp_ids 是我們的 action
    token_logp = log_probs.gather(-1, batch["resp_ids"].unsqueeze(-1)).squeeze(-1)
    
    # 依 RL 演算法計算 advantage 等
    loss = -(token_logp * advantage_mask).sum() / num_valid_tokens
    loss.backward()
    

    因為 prompt_hs 沒有被 detach,梯度會沿著 response 部分回傳到 prompt 部分,等效於一次走完整個序列,但 prompt 只 forward 一次。


    4. 與 gradient checkpointing / mixed precision / DDP 整合

    • gradient checkpointing:
    • 可以只對 response graph 開啟 checkpoint,prompt graph 一般不需要再切。
    • 若 prompt 特別長,可在 prompt 段也設 checkpoint,但要注意不要把 cache 給破壞(照 layer 切即可)。

    • mixed precision (AMP/Fp16/bf16):

    • 保持 prompt & response forward 使用同一個 torch.cuda.amp.autocast 區塊。
    • prompt cached hidden 和 response 的精度必須一致,避免 dtype mismatch。

    • DDP/FSDP:

    • 基本原則:prompt forward 也在每個 rank 上做一次,不要跨 rank 共用 hidden,避免額外通信。
    • 對 FSDP 來說,prompt hidden 是 activation,照樣會被 shard/rebuild,不需要特別處理。
    • 注意 loss scale 及 no_sync() 區段,確保多 step accumulation 時 prompt/response 的 backward 一致。

    建議與注意事項

    1. 常見坑

    1. 快取導致樣本 shuffle 不均
    2. 若你把「相同 prompt 的多個 response」綁在一起,容易造成某些 prompt 被過度訓練。
    3. 建議在 dataset 層維持 樣本級 shuffle,不要把 prompt 當成硬分桶,或定期重組 group。

    4. mask 錯誤導致梯度泄漏

    5. 如果 attention mask 沒處理好,可能出現:response token 看到未來 token,或不同樣本互相看到彼此的 prompt。
    6. 尤其在 concat prefix 時,要確認:

      • padding token 完全被 mask 掉;
      • prefix 與 response 的因果 mask 正確(response 不該看到未來 response)。
    7. policy / value head 不一致

    8. 很多 RL pipeline 會同時跑 policy head + value head。
    9. 如果你只對 policy 路徑用 prompt cache,而 value 還在跑 full sequence,
      會導致兩邊的 feature distribution 不一致。
    10. 建議:兩個 head 共用同一套 prompt+response 拆圖邏輯,或至少在 feature 塊對齊。

    2. 什麼時候值得導入?

    你可以簡單做一個估算:

    • 計算平均 T_prompt / T_resp。
    • 估算你的訓練 step 中,有多少時間是花在 forward(相對於通信/IO)。
    • 目標提速 ≈ T_total / (T_resp + T_prompt / cache_reuse_factor)。

    若粗算下來:

    • 理論加速 > 2x,且你目前的 RL 訓練被 FLOPs-bound(非 IO-bound),那導入很可能值得。
    • 若你被 data loading 或 reward 模型 inference 卡住,則先優化 pipeline 再考慮這一層。

    3. 實務指引(TL;DR)

    • 優先導入場景:
    • RLHF/RLAIF 的對話評分、工具調用評分、長上下文 code RL。
    • prompt 長度是 response 的 3–10 倍。
    • 使用 Qwen3.5-4B 或相近大小模型,GPU 計算是主要瓶頸。

    • 預期收益:

    • 實測可達 3x–7.5x throughput 提升。
    • 允許你把 batch 撐大,減少 gradient accumulation,進一步提高 GPU 利用率。
    • 相同 GPU 成本下,能多跑數倍 rollout 或更長訓練步數。

    • 導入步驟建議:

    • 先在小 batch 上實作 forward_prompt + forward_response_with_prefix,只做 sanity check。
    • 確認與原 full sequence 訓練的 loss/梯度差異在可接受範圍(數值抖動為正常)。
    • 再導入 DDP/FSDP + AMP,逐步拉大 batch 測 throughput。
    • 監控 loss 曲線與最終 RL reward,確認沒有明顯退化。

    只要你的 RL 任務落在「長 prompt / 短 response」區間,RL 訓練版 prompt cache 幾乎就是一次性的大幅成本折扣;對正在做 RLHF/RLAIF 的團隊,值得花 1–2 週工程時間好好實作一版。


    🚀 你現在可以做的事

    • 在現有 RLHF/RLAIF 代碼中量測平均 T_prompt / T_resp,判斷是否達到導入門檻(≥3)
    • 在一個小型實驗中實作 forward_prompt 與 forward_response_with_prefix,對比 full sequence 訓練的 loss/梯度
    • 在實際 Qwen3.5-4B 或現用模型上開啟 prompt cache 實驗,記錄 throughput 與成本變化,評估是否全面導入
  • 用瀏覽器跑 Gemma 4 控機器人

    用瀏覽器跑 Gemma 4 控機器人

    📌 本文重點

    • 只用瀏覽器即可完全離線跑 Gemma 4
    • 結合 WebSerial 可直接控制機器人與 IoT
    • 純前端即可實作迷你 AI agent 控制硬體

    不想把資料丟雲端、又想用 LLM 控機器人?Gemma 4 + Transformers.js + WebGPU 讓你只靠瀏覽器就能離線跑模型、還能直接控制硬體。

    參考實作影片:Gemma 4 fully offline + WebGPU + Reachy Mini(Reddit)
    https://www.reddit.com/r/LocalLLaMA/comments/1ta9mmd/gemma_4_running_fully_offline_on_webgpu_with/


    核心功能:一台電腦 + 一個瀏覽器就夠

    1. 完全離線的瀏覽器 LLM

    這套組合的核心是:

    • Gemma 4:Google 開源 LLM 系列,支援多種量化格式(GGUF / ONNX / JS)。
    • Transformers.js:在瀏覽器裡跑 Hugging Face 模型的 JavaScript 函式庫。
    • WebGPU:用你電腦的顯示卡在「前端」跑推理,不用後端伺服器。

    你可以做的事:

    1. 在本機開啟支援 WebGPU 的瀏覽器(Chrome / Edge / Brave)。
    2. 把公司文件、程式碼丟進前端頁面,讓 Gemma 4 在本機推理,不經過任何外部 API。

    實際效果:隱私資料留在電腦裡,沒有雲端 API log,也不需要申請 OpenAI Key 或部署後端。

    💡 關鍵: 只要一台支援 WebGPU 的電腦與瀏覽器,就能完成完全離線、無雲端依賴的 LLM 推理與控制。


    2. 透過 WebSerial 控制機器人 / IoT

    Reddit 的 demo 裡,用 Transformers.js 跑 Gemma 4,搭配 WebSerial API 直接控制 Reachy Mini 機器人。

    流程概念:

    1. 使用者在瀏覽器輸入:「向右揮手打招呼」。
    2. Gemma 4 把自然語言轉成一段控制指令(例如 JSON 或簡單 DSL)。
    3. JavaScript 把指令透過 WebSerial 傳給機器人控制板(例如 Arduino / microcontroller)。

    你可以照做的行動:

    • 先用 Arduino + USB 線,把一顆 LED 或伺服馬達接到電腦。
    • 寫個簡單的序列通訊協議,像:LED_ON、LED_OFF、SERVO:45。
    • 在網頁裡用 JavaScript:

    js
    const port = await navigator.serial.requestPort();
    await port.open({ baudRate: 115200 });
    // 把 LLM 產生的指令寫進 serial

    先從「LLM 控燈」,再慢慢升級到「LLM 控機器人手臂」。


    3. 純前端的迷你 AI Agent

    有了本地 LLM + WebSerial,你可以在瀏覽器裡做一個小型 AI agent。

    • 理解任務:使用者輸入「每 10 分鐘幫我量一次溫度」。
    • 規劃步驟:Gemma 4 產生一段 JSON 計畫,例如:

    json
    {
    "action": "loop",
    "interval": 600,
    "task": "read_temp"
    }

    • 執行控制:前端 JS 解析 JSON,呼叫對應的 serial 指令。

    可以做的練習:

    1. 先讓 LLM 只輸出固定格式 JSON(用 system prompt 約束)。
    2. 前端寫一個 parser,檢查 JSON 格式合法才發送給硬體。
    3. 加上「模擬模式」(不連接硬體),先在 console 測試 agent 邏輯。

    適合誰用?三種場景舉例

    1. 教學場景:高中 / 大學生的 AI + 機器人課

    • 不用架伺服器,電腦教室只要能開 Chrome。
    • 學生可以:
    • 改 prompt 看機器人動作改變。
    • 寫自己的小指令語言(例如 MOVE LEFT 10)。
    • 觀察 LLM 如何把自然語言轉成這套語言。

    行動建議:

    • 用一台 Reachy Mini 或任何 Arduino 小車當教材。
    • 提供學生一個預先寫好的 HTML + JS 專案,只讓他們改 prompt 和指令 mapping。

    2. 實驗場景:研究邊緣運算 / 隱私的工程師

    • 需要在醫療、工廠、或無網路環境下跑 LLM。
    • 想測試「模型就在裝置上」的延遲和可靠性。

    行動建議:

    • 把現有的 Python LLM pipeline,拆成:
    • 前端:Transformers.js + WebGPU 跑推理。
    • 後端(選配):只收集匿名統計,不傳原始輸入。
    • 對比雲端 API 與本地推理在速度、穩定度上的差異。

    💡 關鍵: 在醫療或工廠等高隱私、高可靠場景,本地 LLM 能在不傳輸原始資料的情況下提供近乎即時的推理與控制。


    3. 家用場景:DIY 簡易家電自動化

    • 例如:
    • 「用自然語言控制窗簾、風扇」
    • 「讓 LLM 幫你排家中設備的定時腳本」

    行動建議:

    • 先用 USB 連接一塊 ESP32 / Arduino 開發板,只控制一顆繼電器或 LED。
    • 設計簡單語句:
    • 「晚上 10 點關燈」→ 轉成 SCHEDULE:22:00:OFF。
    • 用 LLM 把上面這種語句自動產生,再由 JS 解讀和排程。

    怎麼開始:從開啟 WebGPU 到控制第一顆 LED

    步驟一:開啟瀏覽器 WebGPU

    以 Chrome 為例:

    1. 更新到最新版(至少 120 以上會較穩定)。
    2. 在網址列輸入 chrome://flags。
    3. 搜尋「WebGPU」,啟用:
    4. WebGPU(或 Unsafe WebGPU 視版本而定)。
    5. 重新啟動瀏覽器。

    行動檢查:


    步驟二:從 Hugging Face 抓 Gemma 4 模型

    常見三種格式:

    格式 名稱示例 特點 適合誰
    GGUF gemma-4b-it-q4_0.gguf 量化後較小,適合 CPU/GPU 混合 已熟悉 ggml / llama.cpp 生態的人
    ONNX gemma-4b-it.onnx 通用,很多推理引擎支援 想跨平台跑推理的開發者
    JS Transformers.js 專用權重 直接在瀏覽器載入 前端工程師、想快速起跑的人

    操作建議:

    1. 到 Hugging Face 搜尋「Gemma 4」模型庫(例如 google/gemma-2-2b-it,實際名稱依官方更新為準)。
    2. 找到有 transformers.js 或 onnx 標籤的 repo。
    3. 把權重檔放在自己的靜態網站(或本機 dev server)供前端載入。

    Transformers.js 官方文件:
    https://huggingface.co/docs/transformers.js

    💡 關鍵: 透過 Transformers.js 專用權重,可直接在瀏覽器載入 Gemma 4,省去自建推理後端的成本與複雜度。


    步驟三:在瀏覽器跑起簡單 Chatbot

    最低限度的前端結構:

    <script type="module">
      import { pipeline } from '@xenova/transformers';
    
      const chat = await pipeline('text-generation', 'path/to/gemma4/model');
    
      async function ask(prompt) {
        const out = await chat(prompt, { max_new_tokens: 128 });
        console.log(out[0].generated_text);
      }
    
      ask('你現在是一個 Arduino 助理,請用 JSON 說明如何讓 LED 閃爍。');
    </script>
    

    行動建議:

    • 先在 console 裡確認模型可以正常回答,再加上簡單的 <textarea> + <button> 當聊天介面。

    步驟四:把 Chatbot 接到 WebSerial(Arduino)

    1. Arduino 端草稿:

    “`cpp
    void setup() {
    Serial.begin(115200);
    pinMode(13, OUTPUT);
    }

    void loop() {
    if (Serial.available()) {
    String cmd = Serial.readStringUntil(‘\n’);
    if (cmd == “LED_ON”) digitalWrite(13, HIGH);
    if (cmd == “LED_OFF”) digitalWrite(13, LOW);
    }
    }
    “`

    1. 前端 WebSerial + LLM:

    “`js
    async function connectSerial() {
    const port = await navigator.serial.requestPort();
    await port.open({ baudRate: 115200 });
    const writer = port.writable.getWriter();
    return writer;
    }

    async function sendCommandFromLLM(userText, writer) {
    const response = await chat(使用者的指令:${userText}
    請只回應一行指令,LED_ON 或 LED_OFF
    );
    const cmd = response[0].generated_text.trim();
    await writer.write(new TextEncoder().encode(cmd + ‘\n’));
    }
    “`

    1. 實際試用:

    2. 在頁面輸入「開燈」→ LLM 產生 LED_ON → 燈亮。

    3. 在頁面輸入「關燈」→ LLM 產生 LED_OFF → 燈熄。

    這就是從「純前端 LLM」到「瀏覽器裡的迷你 AI agent」的第一步。


    小結:從簡單控制開始,一步步加功能

    建議的練習路線:

    1. 第一階段:在瀏覽器跑起 Gemma 4 chatbot,確認 WebGPU 正常。
    2. 第二階段:用 WebSerial 控制一顆 LED 或一個伺服馬達,先用固定按鈕測試。
    3. 第三階段:讓 LLM 產生中介指令(JSON 或簡單 DSL),由 JS 驗證後再送給硬體。
    4. 第四階段:加入簡單記憶和排程,做出「瀏覽器內的小型 AI agent」。

    只要一台支援 WebGPU 的電腦、一顆開發板,就能在客廳或教室裡體驗「完全離線的 LLM 控機器人」。


    🚀 你現在可以做的事

    • 到 Hugging Face 下載一個支援 Transformers.js 的 Gemma 4 模型,放到本機靜態伺服器測試載入
    • 依文中示例寫一個最簡單的前端 Chatbot,確認在你的瀏覽器上能透過 WebGPU 正常推理
    • 準備一塊 Arduino 或 ESP32,照示例建立 LED_ON / LED_OFF 協議,實作第一個「LLM 控燈」實驗
  • 本地 AI 代理寫程式,也要有 AI 幫你審 PR

    本地 AI 代理寫程式,也要有 AI 幫你審 PR

    📌 本文重點

    • AI 寫程式一定要搭配 AI 審查流程
    • adamsreview 提供多代理、分階段 PR 審查
    • React Doctor 專治 AI 產出的 React 小雷
    • 組合成「AI 寫 + AI 審 + 人類決策」完整 workflow

    當你開始大量用 AI 寫程式時,真正的風險不在「寫不出來」,而在「錯誤、壞味道、性能坑」靜靜被合進主幹,所以現在比起寫程式,更需要好的 AI 審查與補救工具。

    下面用兩個最近爆紅的開源工具 adamsreview 和 React Doctor,帶你組一條「AI 寫程式 + AI 審 PR/修 bug」的實戰流程。


    核心功能:兩個工具,一條龍

    工具總覽

    名稱 核心功能 免費方案 適合誰
    adamsreview 多代理分工的 PR 審查,深度檢查邏輯與安全 完全開源 用 GitHub / GitLab、有 PR 流程的後端或全端團隊
    React Doctor 自動檢測、修正 AI 產出的 React 程式碼 完全開源 用 Claude/ChatGPT 產生 React/TSX 的前端團隊

    接下來分別講清楚:

    1. adamsreview 怎麼把 PR 審查拆給多個 AI 代理,使錯誤更難漏掉。
    2. React Doctor 怎麼專門處理「AI 產生 React code 一堆小雷」這件事。
    3. 最後用這兩個工具,組裝一條可直接抄走的開發 workflow。

    一、adamsreview:多代理分工的嚴謹 PR 審查

    核心功能

    adamsreview 是一個專為 Claude Code 設計的插件(slash commands),重點是:

    1. 多階段、多代理 PR 審查
    2. 不是一次跑完,而是分成好幾個階段:整體變更 → 文件/測試 → 安全/性能 → 修正建議。
    3. 每個階段可啟動平行子代理(sub-agents),例如一個看 API 變更,一個看錯誤處理。
    4. 審查狀態存在本地 JSON 裡,可以在不同命令之間保持上下文。

    5. 更少漏網 bug、更少誤報

    作者在 HN 上提到,它在實戰中比:

    • Claude 內建 /review、/ultrareview
    • CodeRabbit、Greptile

    更常抓到真實 bug,同時少講廢話。

    實際上常被抓到的包括:

    • 新增邏輯沒有對錯誤狀況做邊界檢查
    • 漏更新單元測試或 fixture
    • API 變更與文件不一致
    • 可預期的性能問題(例如重複查詢、無 cache)

    💡 關鍵: 多階段、多代理的拆解方式,讓 adamsreview 比一般單次 /review 更容易抓到真正 bug,且減少冗長誤報。

    1. 直接嵌入現有 PR 工作流
    2. 提供像 /review、/codex-review、/fix 等命令,照著你原本用 Claude Code 的習慣延伸。
    3. 可搭配 Codex CLI 與 PR bot,在 PR 上直接留下 AI 審查留言。
    4. 狀態存在檔案裡,方便在 CI 或本地反覆跑不同階段的檢查。

    適合誰用

    幾個具體場景:

    • 有正式 PR 流程的後端/平台團隊

    例如:用本地 LLM 或 Claude 幫你生成 service / handler,透過 adamsreview 做一輪「AI 審 PR」,再交給人類最後確認。

    • 資深工程師很忙的小團隊

    初階工程師用 AI 寫功能,先交給 adamsreview 初審,減少 reviewer 花時間抓基礎錯誤。

    • 正在導入 AI coding,但怕品質失控的團隊

    讓「AI 生成程式碼」必須經過「AI 多代理審查」,有規則可循,而不是全憑 reviewer 心情。

    怎麼開始:最小安裝步驟

    原始專案:https://github.com/adamjgmiller/adamsreview

    以下是一個「最短路徑」,讓你在現有 GitHub PR 流程中接上 adamsreview:

    1. 準備環境

    2. 需要:

      • 有權使用 Claude Code 並可安裝插件(通常是付費方案)。
      • 本機有 git + Node.js(或作者指定的執行環境)。
    3. 安裝與設定

    在你的開發機或開發容器中:

    bash
    git clone https://github.com/adamjgmiller/adamsreview
    cd adamsreview
    # 若有提供安裝腳本
    npm install # 或 pnpm/yarn

    • 依照 repo README 設定環境變數(通常包含 Claude/Codex API key)。

    • 在 Claude Code 中載入插件

    • 打開 Claude Code(或支援的 IDE 插件)。

    • 依 README 說明匯入 slash commands。
    • 你會看到新增的命令,例如:/review、/fix。

    • 在 CI / PR 流程中接上(GitHub Actions 範例)

    在 .github/workflows/pr-review.yml 增加一個簡化版 workflow:

    “`yaml
    name: AI PR Review

    on:
    pull_request:
    types: [opened, synchronize]

    jobs:
    ai-review:
    runs-on: ubuntu-latest

       steps:
         - name: Checkout
           uses: actions/checkout@v4
    
         - name: Setup Node
           uses: actions/setup-node@v4
           with:
             node-version: '20'
    
         - name: Install adamsreview
           run: |
             git clone https://github.com/adamjgmiller/adamsreview
             cd adamsreview && npm install
    
         - name: Run adamsreview
           env:
             CLAUDE_API_KEY: ${{ secrets.CLAUDE_API_KEY }}
           run: |
             cd adamsreview
             # 依專案提供的 CLI 指令
             npm run review -- ../
    

    “`

    這樣每次有人開 PR,就會自動觸發 AI 審查並在 PR 留言(實際指令依 repo 說明調整)。


    二、React Doctor:專治 AI 產出的 React 小雷

    官方 repo:https://github.com/millionco/react-doctor

    它在 README 的第一句就是:「Your agent writes bad React. This catches it」。重點就是:AI 幫你產生的 React/TSX 常常「能跑,但不安心」。

    核心功能

    1. 針對 React/TSX 的靜態檢測與修復

    2. 專門用來掃描 React 專案(JSX/TSX),找到常見的壞味道與 bug。

    3. 例如:
      • 在 useEffect 中漏依賴
      • 不必要的 re-render
      • 不穩定的 key
      • props 型別不一致
    4. 部分問題可以自動產生修正 patch,直接套用。

    5. 和 AI 代理配合運作

    它假設你已經在用 AI(Claude、ChatGPT、Cursor 等)生成元件或 hook:

    • 先讓 AI 產出 code
    • commit 前跑 React Doctor:快速找出「AI style 錯誤」
    • 必要時讓 React Doctor 幫你修補。

    • TypeScript 友善

    • 專案本身用 TypeScript 寫,也善用現有型別資訊。

    • 如果你本來就用 TS + React,導入成本很低,直接把現有 tsconfig、型別檔當基礎。

    💡 關鍵: React Doctor 把「AI 寫得能跑」提升到「依 React/TS 最佳實務可維護」,特別適合大量由 AI 生成的 UI 程式碼。

    適合誰用

    幾個典型情境:

    • 用 Claude/ChatGPT 幫你生 UI 元件

    例如設計稿轉 React Component:

    • AI 負責「寫得出來」。
    • React Doctor 負責「寫得對、好維護」。

    • React 新手 + AI 輔助開發

    新手可能看不出 AI 產生的 code 有哪些壞習慣,React Doctor 可以當成「自動 code review 老師」。

    • 已有大型 TypeScript + React 專案

    部分模組開始用 AI 重構或新增功能,用 React Doctor 當 Safety Net,避免 AI 把舊 code 改壞。

    怎麼開始:在 TS 專案快速啟用

    假設你有一個現成的 React + TypeScript 專案:

    1. 安裝 React Doctor

    專案目錄下:

    bash
    npm install react-doctor --save-dev
    # 或
    pnpm add -D react-doctor

    1. 新增設定檔(若有需要)

    參考 repo 中的樣板(實際檔名跟範例以官方 README 為準):

    bash
    npx react-doctor init

    這通常會產生一個設定檔,例如 react-doctor.config.ts,你可以指定:

    • 要掃描的資料夾(例如 src)
    • 要啟用的規則

    • 在 package.json 加上腳本

    json
    {
    "scripts": {
    "doctor": "react-doctor check src",
    "doctor:fix": "react-doctor fix src"
    }
    }

    1. 在 Git hooks / CI 中啟用

    2. 透過 Husky 或 lint-staged,在 pre-commit 或 pre-push 跑:

      bash
      npx react-doctor check src

    3. 或在 GitHub Actions 加一個 job:

      yaml
      - name: React Doctor
      run: npm run doctor

    這樣每次有人把 AI 產的 React code 推上來,就會被 React Doctor 先掃過一次。


    三、組裝一條「AI coding + AI code review/repair」工作流

    最後用文字幫你拼成一個可以直接採用的流程,從「AI 寫 code」到「AI 審查 + 修正」:

    1. 開發階段:AI 寫程式

    2. 使用本地 LLM、Claude Code 或 ChatGPT:

      • 讓 AI 產出後端 handler、service、React 元件。
      • 人類工程師只負責寫 prompt + 調整架構。
    3. 前端部分:React Doctor 抓小雷

    4. 每次 AI 生成或修改 React/TSX 檔案:

      • 本地跑 npm run doctor 檢查。
      • 對於可自動修正的問題,跑 npm run doctor:fix。
    5. 把這個步驟固定在:

      • pre-commit hook
      • 或 VS Code Task / npm script
    6. 提交 PR:adamsreview 做多階段 PR 審查

    7. 開 PR 後,GitHub Actions 觸發 adamsreview:

      • 階段 1:總覽差異,找出風險區域。
      • 階段 2:針對測試、錯誤處理、安全性做專門檢查。
      • 階段 3:產生具體修正建議或 patch。
    8. PR 上自動留下 AI comment,方便 reviewer 快速聚焦真正問題。

    9. 人類最後把關

    10. Reviewer 看:

      • React Doctor 的報告(前端)
      • adamsreview 的 PR 評論(後端/全端)
    11. 決定哪些建議要採用,哪些視情況忽略。
    12. 合併前至少確保:
      • 所有必跑的 React Doctor / adamsreview 任務都綠燈。

    💡 關鍵: 重點不是「全自動合併」,而是用 AI 把最耗時、最容易忽略的細節掃一遍,再由人類做最後決策。

    這條工作流的重點不是「全自動」,而是:

    • 把 AI 寫程式變成可控的流程,而不是隨意貼 paste code。
    • 把最耗時、最容易忽略的細節(React 小雷、邊界條件、安全性)交給專門的 AI 工具來抓。

    實作上,你可以先選一個小模組試行:

    • 前端導入 React Doctor。
    • 後端/全端導入 adamsreview。
    • 兩週後檢查:PR 審查時間、有 bug 的 PR 比例是否下降,再決定要不要擴大到整個 repo。

    用 AI 寫程式已經變成常態,下一步是在你的團隊裡,建立一套 「AI 寫 + AI 審 + 人類決策」的固定流程,讓速度與品質可以同時兼顧。

    🚀 你現在可以做的事

    • 打開 GitHub,分別把 adamsreview 與 React Doctor repo 加到你的星標與閱讀清單
    • 在一個側專案或小模組上,先實驗接上 React Doctor 的 npm run doctor / doctor:fix 腳本
    • 在現有 repo 新增一個簡單 GitHub Actions workflow,試跑一次 adamsreview 的 AI PR 審查流程
  • Google 要把 OS 變成 Agent 平台嗎?

    Google 要把 OS 變成 Agent 平台嗎?

    📌 本文重點

    • Google 企圖把 OS 重寫為 Agent 優先的平台
    • 平台競爭從「搶入口」轉向「搶工作流程」
    • 開發者需同時服務「人類」與「Agent」兩條產品線

    Google I/O 2026 的真正賭注,不在於 Gemini 4 有多強,而是要把作業系統重寫成一個為 Agent 服務的「新 API 平台」。如果這一步成功,應用程式的單位將從「App」變成「工作流程」,OS 的主戰場也會從桌面 UI 轉移到 Agent 流程調度。**

    這次的產品組合——Gemini 4、Aluminium OS、Android XR、AI 眼鏡,再加上與 Apple 的合作——本質上是 Google 在打同一場仗:把 Agent 拉到「系統層」而不是「App 層」來運作,並試圖重寫平台規則。


    一、Google 的真正企圖:把 Agent 變成「新一代 App」

    從開發者視角看,這場 I/O 有三個關鍵訊號:

    1. 模型:Gemini 4 的定位從「聊天模型」轉向「行動執行引擎」

    不管 Google 怎麼包裝 Gemini 4 的推理能力提升,最重要的不是 SOTA benchmark,而是:

    • 它被綁在 Aluminium OS 的系統層,
    • 被接到 Android XR 的跨裝置 runtime,
    • 被塞進 AI 眼鏡這種「長時間在場」的介面。

    這意味著:Google 不再把模型當雲端 API,而是當 OS 的核心 runtime。

    1. OS:Aluminium OS 是「Agent-first OS」,不是 Chrome OS 2.0

    Aluminium OS 的關鍵不在 UI,而在 系統 API 結構:

    • OS 內建 Agent 層:檔案、行程、通知、網路權限都可以被 Agent 調度;
    • 支援 離線/邊緣推理:在端上跑縮小版 Gemini 4,減少對雲端的依賴;
    • 更細緻的 權限與審計機制:讓 Agent 能在可監管的軌道內運作。

    這對開發者意味著:

    • 你不再只是寫前端 UI 或後端 API,而是寫「可被 Agent 調用的能力模組」;
    • 你的 App 可能沒有使用者介面,只有被 Agent 呼叫的 workflows;
    • 「寫給人用」與「寫給 Agent 用」 會分成兩種產品線。

    • 跨端:Android XR 不是新系統,是新「執行邏輯」

    Android XR 被描述成「跨手機、機器人、車載、眼鏡」的統一平台。從 Agent 角度看,它在做的是:

    • 把不同終端的 感知能力(感測器、鏡頭、麥克風) 和 行動能力(通知、撥號、支付、控制設備) 抽象成一組可調用的 API;
    • 讓同一個 Agent 可以跨裝置持續任務,而不是每一台裝置都跑一個孤立 chatbot。

    💡 關鍵: Google 正在把 OS 從「人點按的介面」重構為「Agent 調用的能力平台」,讓模型變成系統級 runtime,而非單純雲端 API。

    結論是:Google 正在把 OS 從「人點按的介面」重構為「Agent 調用的能力平台」。 這也是為什麼這次 I/O 會被視為一次真正的「平台嘗試」,而不只是模型發表會。


    二、入口 vs. 工作流程:Google、Apple、OpenAI、Anthropic 的路徑分叉

    產業策略上,現在 AI 平台分成兩條線:搶入口 vs. 搶工作流程。

    1. Google × Apple:誰掌控 iPhone 的預設 Agent?

    最敏感的一步,是 Google 與 Apple 的合作。若 Gemini 成為 Siri 背後的推理引擎,或至少成為 iOS 上的某種預設 AI 選項,這會帶來幾個後果:

    • 入口層主權切割:

    • Apple 繼續掌控 UI、隱私策略、系統權限與「預設選擇」;

    • Google 則掌控背後的語言推理與部分 Agent 能力。

    這讓 iPhone 的 AI 體驗變成「Apple 皮 + Google 大腦」。

    • 預設選擇戰升級為「預設 Agent 戰」:

    這已不是預設搜尋引擎的戰爭,而是預設 日常任務被誰的 Agent 接管:

    • 你在 iPhone 上說「幫我安排明天行程」,是 Apple 的本地 Agent 處理?還是交給 Google 的雲端 Agent?
    • Apple 會限制第三方 Agent 的系統權限,保持「入口控制權」,但這次不得不讓出部分「推理能力」給 Google。

    換句話說:Apple 在守入口,Google 在滲透工作流程——雙方是互相利用,也是在預設 AI 的控制權上互相牽制。

    2. OpenAI:用 DeployCo 搶「企業工作流程」

    對比之下,OpenAI 走的是另一條線:從 ChatGPT 入口做到 DeployCo 這種深度整合。根據 The Decoder 對 DeployCo 的分析:

    • OpenAI 借鏡 Palantir,把 AI 深度嵌入企業運營,
    • 透過顧問+實作,打造「實務工作流程壁壘」,
    • 重點不在 OS,而在「把模型變成企業習慣的工作方式」。

    再對照 OpenAI 官方在「How enterprises are scaling AI」強調的:

    • 信任機制、治理架構、工作流設計、質量監控——這些都是 Agent 真正落地的前提;
    • 企業端看的是 可控性與治理,而不是模型多聰明。

    OpenAI 的策略是:不搶裝置入口,而是搶企業的業務流程。入口可能在 Microsoft、在瀏覽器、在第三方 App,但最後的「AI 工作流內核」由它主導。

    3. Anthropic & AWS:把 Agent 變成「企業級服務層」

    Anthropic 則靠著 Claude 平台在 AWS 一般可用,把自己鎖定在 企業雲端層:

    • 透過 Claude Managed Agents,提供多 Agent、代碼執行、網頁搜尋、Files API 等完整能力;
    • 與 Amazon Bedrock 並行,滿足不同地區、不同治理要求的企業;
    • 搭配 AWS 的認證、計費與 SLA,變成企業 IT 生態中的「安全 Agent 層」。

    AWS 自己也沒有閒著:Reddit 上討論熱烈的 Amazon Bedrock AgentCore Payments,直接給 Agent 一個可控的錢包,透過 x402 協定讓 Agent 能自主支付 API、資料、甚至其他 Agent 的服務費。這把 Agent 正式推入 「自我消費」的商業模式。

    總結這三家:

    • Google:從 OS 下手,搶「消費者端日常工作流程」;
    • Apple:死守入口與預設控制權,把 AI 當系統功能而非平台;
    • OpenAI / Anthropic / AWS:深挖「企業工作流程」與治理,讓 Agent 成為企業內部的服務層。

    💡 關鍵: 平台之戰已從「誰的模型最強」轉變為「誰能掌控日常與企業工作流程中的預設 Agent 與服務層」。

    真正的分水嶺不再是「誰模型比較強」,而是:誰能把 Agent 變成穩定、可信、可治理的「新 OS / 新雲 API」。


    三、Agentic OS 的技術門檻:開發者面對的是一個「後 RAG 時代」

    從技術與生態來看,Google 這次要做的 Agentic OS,其實踩在幾個未爆彈上。

    1. 離線推理 + 隱私:OS 級 Agent 的必要條件

    要讓 Agent 住在 OS 裡,而不是只在雲端跑聊天介面,至少要滿足:

    • 端上推理能力:部分任務不再需要雲,這對行動裝置與眼鏡尤為關鍵;
    • 隱私與合規:日常操作由 Agent 接管,意味著它會接觸:

    • 郵件、檔案、行事曆、訊息、甚至感測器資料;

    • 如果沒有系統級的權限沙箱與審計軌跡,企業與監管不可能買單。

    Google 想用 Aluminium OS + Android XR 把這些變成 default capability,這對開發者的意味是:

    • 你必須設計 可部分端上、部分雲端運行 的 Agent 工作流;
    • 必須考慮 資料分界線:哪一段邏輯可以交給端上模型,哪一段要上雲端;
    • 隱私與權限將從「App = 沙箱」變成「Agent = 受控但跨 App 的 orchestrator」。

    2. 後 RAG 時代:Agent 不是大型 chatbot,而是長鏈任務調度器

    Towards AI 上那篇 〈RAG Was Built for Chatbots. Agents Are Breaking It〉 已經說得很白:

    • 傳統 RAG 在 Agent 場景下,85% 的算力被消耗在檢索;
    • 任務完成率僅 50–60%,瓶頸不在模型,而在架構;
    • Agent 的需求不是「找幾段文件放進 context」,而是:

    • 多步決策;

    • 多工具、多 API 協同;
    • 長時間狀態管理。

    💡 關鍵: 當 85% 算力被卡在檢索、任務完成率只有 50–60% 時,問題已不在模型,而在整個 RAG 架構與任務調度設計。

    如果 Google 要在 OS 裡跑 Agent,勢必要提供一套 取代 RAG 的新基礎架構:

    • 面向 Agent 的記憶、工具調度、工作流引擎;
    • 不只是向量資料庫,而是 任務狀態存儲+決策快取;
    • 對開發者來說,這會變成新的「Agent SDK / Runtime」,類似當年的 Android SDK——只不過這次是給 Agent 不是給人類使用者。

    若這一層沒有被做好,所謂 Agentic OS 就只是「在 OS 裡執行一個聊天程式」而已。


    四、這波變化對開發者與使用者的實際意義

    對開發者:把產品線拆成「給人用」與「給 Agent 用」

    接下來 2–3 年,開發者會遇到幾個具體決策:

    1. 設計「Agent-friendly API」:

    2. 你的服務需要提供乾淨的 API、明確的 schema、錯誤碼,方便 Agent 理解與重試;

    3. 支援細緻的權限與計費,甚至要預留 Agent 自付費 的接口(對接像 AgentCore Payments 這種機制)。

    4. 把「工作流程」變成主要產品:

    5. 不要只想「做一個 App」,而要想「做一個 Agent 能代你完成的 end-to-end workflow」;

    6. 多思考如何讓自己的服務嵌進 Gemini / Claude / OpenAI 的 Agent 流程,而不是只做獨立前端。

    7. 投入治理與可監管性設計:

    8. 企業客戶會問的不是「你用了哪個模型」,而是:

      • 誰審核 prompt?
      • 誰可以查看執行紀錄?
      • 失誤怎麼追責?
    9. 這正是 OpenAI、Anthropic、AWS 正積極提供的能力,也是 Google 目前相對弱的一環——這也剛好是開發者可以補位的地方。

    對一般使用者:你的日常操作即將被「默默接管」

    對一般使用者來說,這一波不是某個 App 升級,而是「你與裝置互動的基本單位」要變了:

    • 你不再是點開十個 App;你是說「幫我處理這件事」,然後 Agent 幫你:

    • 看信、回信、訂票、排程、填表、付款;

    • 你甚至不一定知道哪個 App 在背後運作,因為它們變成被 Agent 調用的「服務模組」。

    這會帶來兩個風險與一個現實:

    1. 風險一:控制權更難感知

    2. 誰是預設 Agent?

    3. 它用哪個模型?
    4. 它把你的資料送到哪裡?
    5. 你可能只看到一個看似溫和的系統助理,背後卻是 Google / Apple / OpenAI 的治理博弈。

    6. 風險二:錯誤與偏差變成「系統層問題」

    7. 過去是一個 App 做錯;

    8. 未來是一個 Agent 在 OS 層做錯——影響範圍更廣,責任歸屬也更模糊。

    9. 現實:你很難完全不參與

    10. 工作場所會導入企業 Agent;

    11. 手機 OS 會推送系統級 AI 功能;
    12. 你能做的不是「不用」,而是:

      • 理解哪一些任務適合交給 Agent;
      • 認真看一次權限與預設設定;
      • 在關鍵決策上保持人工覆核。

    最後一句話:

    Google I/O 2026 是 Google 最接近重新定義「作業系統是什麼」的一次嘗試,但真正的勝負不在模型 SOTA,而在能否把 Agent 變成穩定、可信、可監管的「新 OS API」。

    對開發者而言,現在就該開始把產品拆成「給人用」與「給 Agent 用」兩條線,把自己的服務設計成可被 Agent 調度的能力;對使用者而言,則要學會把「預設 AI」視為系統級選項,像看待隱私設定一樣認真檢視——因為這次被改寫的,不只是你裝了哪個 App,而是你每天怎麼操作電腦與手機這件事本身。

    🚀 你現在可以做的事

    • 檢視現有服務的 API 設計,調整為適合 Agent 調用的「能力模組」
    • 追蹤 Gemini 4、Android XR、Aluminium OS 與 Claude Managed Agents 的開發文件與 SDK
    • 打開手機與工作環境中的預設 AI/Agent 設定,逐一檢查權限與預設選項
  • 低延遲語音 AI 架構實戰解析

    低延遲語音 AI 架構實戰解析

    📌 本文重點

    • 目標是在 200–400ms 內提供高品質雙向語音互動
    • 關鍵在通訊管線穩定與三模型 streaming 並行
    • 難點是 tail latency 與企業網路環境下的可用性
    • 先用 WebRTC/WS + 開源模型做 MVP 再優化

    要把GPT‑5 級推理塞進即時通話,最大痛點是:總延遲必須壓在 200–400ms 內,還要撐住大量並發。這篇用 OpenAI 近期的語音架構做藍本,從通訊層、模型層、系統層拆解,並給出一個用「常見雲 + WebRTC/WS + 開源語音模型」的最小可行方案(MVP),協助你評估:

    • 專案能不能做到「類 GPT-Realtime-2」的體驗
    • 目前架構要改哪些地方
    • 延遲預算怎麼抓、實測怎麼調

    重點說明:三層拆解你應該先想清楚什麼

    1. 通訊層:WebRTC / Streaming API 管線

    核心結論:語音幀越小、管線越穩定,LLM 才有操作空間。

    關鍵設計:

    • 雙通道設計:
    • WebRTC:負責雙向音訊(RTP),盡量 P2P,失敗時回退 TURN/Relay
    • WebSocket / gRPC streaming:負責把編碼後音訊送進推理後端,收 TTS 音訊回來
    • 幀大小與編碼:
    • 單向 20ms 幀是常見折衷(Opus 20ms/packet),RTT + 解碼後約 40–60ms
    • OpenAI 類似設計:低 bit‑rate Opus / 自家 codec + 小幀 + 伺服端聚合
    • 回退策略:
    • NAT/防火牆下 P2P 常失敗,要有 ICE + TURN,並在 handshake 階段就降級到「WebRTC → TURN relay → 伺服器」模式

    💡 關鍵: 前端小幀 + 後端穩定回退(ICE + TURN)是把延遲壓到 200–400ms 的第一道門檻

    2. 模型層:語音↔文字↔推理鏈路的裁剪與並行

    核心結論:不要把語音→文字→LLM→TTS 串成一條同步鏈,要做 streaming 並行。

    典型 full pipeline:

    1. 語音 ASR:Speech → Text
    2. 文字 LLM:Text → Response tokens
    3. TTS:Text → Speech

    在低延遲場景下可以這樣優化:

    • 早啟動推理:
    • ASR 用 streaming 模式,每 100–200ms 一個 partial transcript
    • 當句子結構「大致明朗」時(看到疑問詞或語尾),就把目前 transcript 丟給 LLM,不用等語音結束
    • 分段生成 + streaming tokens:
    • LLM 開啟 streaming,邊出 token 邊餵給 TTS
    • 控制 max_tokens / per-turn token budget,避免一次生成長篇大論造成尾端延遲
    • TTS 緩衝策略:
    • 不要等完整句子才播,通常 150–300ms 音訊緩衝就可以開始播放
    • 但也不能太小,避免「一卡一卡」;常見做法是根據 網路 jitter + 解碼時間 動態調整

    OpenAI 最新的 GPT-Realtime-2 / -Translate / -Whisper 其實就是把這條鏈路收斂成幾個特化模型,讓內部共享語音表徵與推理能力,減少中間編碼/解碼開銷。你在自建時不一定能做到單一多模態模型,但至少要做到三模型 streaming 並行。

    💡 關鍵: 把 ASR、LLM、TTS 並行 streaming,通常能把首次開口時間從秒級壓到 300ms 左右

    3. 系統與部署層:分布式推理與 tail latency 控制

    核心結論:平均延遲不難,難的是 99th percentile。

    設計要點:

    • 模型路由與排程:
    • 輕量語音模型(ASR/TTS)可以 多實例 + 每 GPU 多 worker,吃滿 GPU
    • 重 LLM 建議走 集中式推理叢集 + router,依 session 粘性綁定同一实例
    • GPU 利用率:
    • 啟用 batching + token 并行,但要對語音場景限縮 batch size,避免增加 tail latency
    • 長回應可切段生成:先生成 1–2 秒的語音對應文字,再補充後半段
    • tail latency 監控:
    • 重要指標:錄音開始 → 第一個回傳音訊 的 p50/p95/p99
    • 以 tracing 把 pipeline 切開:上傳 / ASR / LLM queue / LLM compute / TTS / 下行網路
    • 一旦 p99 失控,先檢查 排程佇列(排隊時間)而不是模型本身

    💡 關鍵: 真正破壞體驗的是 p99 延遲而不是平均值,監控時要把 queue time 單獨拉出來看


    實作範例:一個最小可行架構(MVP)

    架構概覽

    • 前端:Browser WebRTC(音訊 capture) + WebSocket(控制訊息)
    • 後端:
    • Signaling + API Gateway:Node / Go 都可
    • gRPC streaming 到推理服務
    • 推理服務:Python + 開源 Whisper streaming + 開源 LLM + VITS/TTS(示意)

    前端:WebRTC + WebSocket 管線

    // 簡化版:建立 WebRTC 傳音訊 + WS 傳控制
    const pc = new RTCPeerConnection({
      iceServers: [{ urls: 'stun:stun.l.google.com:19302' }]
    });
    
    const ws = new WebSocket("wss://your-api.example.com/signaling");
    
    async function startCall() {
      const stream = await navigator.mediaDevices.getUserMedia({ audio: true });
      stream.getAudioTracks().forEach(t => pc.addTrack(t, stream));
    
      pc.onicecandidate = e => {
        if (e.candidate) ws.send(JSON.stringify({ type: 'candidate', data: e.candidate }));
      };
    
      pc.ontrack = e => {
        // 收到 TTS 音訊(伺服端用 WebRTC 回推)
        const audio = document.getElementById('remote') as HTMLAudioElement;
        audio.srcObject = e.streams[0];
      };
    
      const offer = await pc.createOffer({ offerToReceiveAudio: true });
      await pc.setLocalDescription(offer);
    
      ws.onopen = () => {
        ws.send(JSON.stringify({ type: 'offer', data: offer }));
      };
    
      ws.onmessage = async (msg) => {
        const { type, data } = JSON.parse(msg.data);
        if (type === 'answer') {
          await pc.setRemoteDescription(data);
        }
      };
    }
    

    注意:

    • 幀大小主要在伺服端設定 Opus encoder(例:20ms),前端維持預設即可
    • 若 WebRTC 被防火牆擋住,signaling 伺服端要下指令讓前端切換為 WebSocket 直接上傳 PCM/Opus 模式

    後端:gRPC streaming 推理服務(示意)

    假設有一個 SpeechService 接收 Opus 幀,回傳已編碼好的音訊幀:

    // speech.proto
    service SpeechService {
      rpc Converse(stream AudioFrame) returns (stream AudioFrame) {}
    }
    
    message AudioFrame {
      bytes data = 1;      // Opus 或 raw PCM
      int64 timestamp = 2; // client capture ts
    }
    

    伺服端 Python(簡化,忽略實際音訊處理細節):

    class SpeechService(servicer_pb2_grpc.SpeechServiceServicer):
        async def Converse(self, request_iterator, context):
            # 1) 啟動 ASR/LLM/TTS 協程
            asr_queue = asyncio.Queue()
            llm_queue = asyncio.Queue()
            tts_queue = asyncio.Queue()
    
            async def asr_worker():
                async for frame in request_iterator:
                    # 解碼 Opus -> PCM -> ASR partial text
                    text_partial = asr_model.transcribe_stream(frame.data)
                    await llm_queue.put(text_partial)
    
            async def llm_worker():
                async for partial in llm_queue:
                    # 送入 LLM streaming,邊出 token 邊丟給 TTS
                    async for chunk in llm.stream(partial, max_tokens=64):
                        await tts_queue.put(chunk.text)
    
            async def tts_worker():
                async for txt in tts_queue:
                    # 生成短語音片段(200–300ms)
                    audio_bytes = tts_model.synthesize(txt)
                    yield speech_pb2.AudioFrame(
                        data=audio_bytes,
                        timestamp=int(time.time() * 1000)
                    )
    
            await asyncio.gather(asr_worker(), llm_worker(), tts_worker())
    

    實務上你會:

    • 用 更細緻的 queue 協調(包含會話 ID、句子邊界)
    • 控制 llm.stream 的 token 長度與 stop 條件,避免超長句
    • 在 TTS 部分先緩衝幾個 frame,再開始透過 WebRTC/WS 推到 client

    延遲 budget 規劃(示意)

    在穩定網路下可以先抓:

    • 上行錄音 + 傳輸:40–80ms(20ms 幀 + RTT)
    • ASR streaming:40–80ms(小模型 + GPU)
    • LLM 推理:80–150ms(取決於 token 數與模型大小)
    • TTS 生成 + 下行傳輸:60–120ms

    整體 p50 目標:220–350ms 第一個回應音訊開始播放。

    優化策略:

    • 第一輪回應:用 較短回應模板(像「嗯、好的,我來看一下…」)快速回覆,爭取後面長推理時間
    • 持續對 ASR/LLM/TTS 做 A/B test:看哪一段是主要瓶頸,優先調那裡的 model size / batch / GPU 排程

    建議與注意事項:幾個常見坑

    1. NAT / 防火牆導致 WebRTC P2P 失敗

    • 坑點:只測局域網或開放網路,實際部署到企業網路立刻掛掉
    • 建議:
    • 一開始就部署 TURN server,並在前端暴露 ICE 連線狀態,回報到後端
    • 若連線失敗,API 層切到 純 WebSocket 音訊通道,雖然成本高但能保證可用性

    2. 語音切段過粗,造成「打斷感」

    • 坑點:以 1 秒幀或整句才送 ASR,LLM 只在句尾發言,對話像對講機
    • 建議:
    • 200ms 以內 的 audio chunk;ASR 使用 partial result callback
    • 根據語氣停頓(VAD)+ 標點預測,判斷何時啟動 LLM 回應

    3. TTS 緩衝策略不當,導致「一卡一卡」

    • 坑點:
    • 緩衝太短 → 網路 jitter 就卡
    • 緩衝太長 → 首次開口延遲拉高
    • 建議:
    • 先以 250ms 緩衝 做 baseline,再按實測 jitter 動態調整在 200–400ms
    • 在 client 端維護一個小 buffer,利用 AudioContext / Web Audio API 自行排程播放,而不是一次性丟給 <audio>

    4. GPU 利用率 vs tail latency 的拉扯

    • 坑點:最大化 batch size 很爽,但 p99 延遲爆炸
    • 建議:
    • 把語音場景的推理服務與一般 chat/RAG 分開,語音路徑限制 max batch size
    • 使用 token-level scheduling(類似 OpenAI 做法),避免長上下文會話拖累短 query

    對專案的實際好處

    • 如果你現在線上只有「按鈕錄音 → 傳檔 → 回文字」,這套設計可以讓你在 1–2 週內做出可 demo 的雙向語音助理
    • 用 WebRTC/WS + 開源模型的 MVP,可以先驗證:
    • 使用者對 latency 敏感度
    • 需要多強的推理(是否真的要 GPT‑5 級推理)
    • 實際 GPU 成本與擴展上限
    • 後續要接上 OpenAI 類似 GPT-Realtime-2 的託管服務時,這套三層思路與接口方式幾乎可以直接沿用,只是把內部 ASR/LLM/TTS 換成單一多模態 API。

    🚀 你現在可以做的事

    • 在現有專案中畫出完整語音管線,標註各節點預估延遲(上傳、ASR、LLM、TTS、下行)
    • 用 WebRTC + WebSocket 加上任一開源 Whisper + TTS,實作一個能雙向講話的最小 demo
    • 部署基本的 tracing(例如在每一階段打 log),實測並記錄「錄音開始 → 第一個回應音訊」的 p50/p95/p99 數據
  • 本地跑 Microsoft 級語音 AI:vibevoice.cpp 入門

    本地跑 Microsoft 級語音 AI:vibevoice.cpp 入門

    📌 本文重點

    • 全本地 TTS + 長語音 ASR + 語者分離,無需雲端
    • 約 30 秒錄音即可 voice clone 自己聲線
    • C++ 實作、支援多後端,推論階段完全不用 Python
    • 很適合會議逐字稿、客服分析與離線語音助手

    一句話先說清楚:vibevoice.cpp 是一套「全本地」的 TTS + 長語音 ASR + 語者分離工具,不用 Python、不上雲,就能在自己機器裡跑出接近 Microsoft VibeVoice 等級的語音 AI。

    原始專案與說明:https://github.com/mudler/vibevoice.cpp(C++ 移植自 Microsoft VibeVoice: https://github.com/microsoft/VibeVoice)


    核心功能:你能馬上用來做什麼

    1. 24kHz 高品質 TTS + 30 秒聲音就能 voice clone

    vibevoice.cpp 內建 TTS 引擎,支援 24kHz 輸出,適合旁白、影片解說、產品語音回應等場景。最大的亮點是:

    • 約 30 秒的語音樣本(.wav / .mp3 都可,建議乾淨無 BGM)
    • 用專案提供的轉換腳本,把你的聲音轉成 gguf voice 檔
    • 之後輸入文字,就能用你的聲線合成語音

    💡 關鍵: 約 30 秒乾淨錄音就能完成 voice clone,是進入個人化 TTS 的最低門檻之一

    實作步驟(voice clone 概念流程):

    1. 準備一段約 30 秒的個人口播,儘量在安靜環境錄製。
    2. 取得原始 VibeVoice 的 .pt 聲音權重(或官方樣例聲音)。
    3. 使用 vibevoice.cpp repo 裡的 scripts/convert_voice_to_gguf.py 將聲音轉成 .gguf 語音檔。
    4. 在 TTS 命令中指定這個 voice 檔,就能生成你的聲線。

    提示:沒有 Python 推論,但轉換 .pt → .gguf 這一步需要一次性使用 Python。轉好後推論階段完全不用 Python。


    2. 長語音 ASR + 語者分離,一次處理十幾分鐘錄音

    vibevoice.cpp 背後是約 7 億參數的模型,實測可以處理長達十幾分鐘的錄音(作者在 Reddit 提到測到約 17 分鐘),並做到:

    • 自動逐字稿(ASR)
    • 自動切段(按時間區段)
    • 自動標註不同說話者(Diarization)

    💡 關鍵: 7 億參數模型可穩定處理約 17 分鐘長錄音,適合會議與客服等實際業務場景

    也就是:丟一整段會議錄音進去,輸出就會像這樣:

    [00:00.0 - 00:12.3] Speaker 1: 大家好,今天會議主要討論 Q3 產品排程…
    [00:12.3 - 00:25.7] Speaker 2: 我先更新一下研發這邊的進度…
    ...
    

    快速實作想法:

    • 會議錄音 → 丟給 vibevoice.cpp → 拿回文字 + 誰在說話 → 直接貼進 Notion、Confluence 或公司內網系統。
    • 客服錄音 → 一批檔案跑 ASR + 語者分離 → 拿到客服與客戶對話文字,後續再用本地 LLM 做情緒分析或關鍵字統計。

    3. 跨平台、本地推論、無 Python 推論依賴

    vibevoice.cpp 用 C++ + ggml 實作,支援多種硬體後端:

    • CPU(x86 / ARM)
    • CUDA(NVIDIA GPU)
    • Metal(Apple Silicon / macOS)
    • Vulkan(支援 Vulkan 的 GPU 平台)

    這幾件事對實際部署很關鍵:

    • 不需要在伺服器上裝一大堆 Python/conda,推論階段就是一個二進位 + gguf 模型檔。
    • 更容易嵌入既有系統:C ABI 讓你在 C/C++、Rust、Go、甚至 Node.js(透過 FFI)裡都能呼叫。
    • 適合沒有外網、或對資料保密要求高的內網環境。

    💡 關鍵: 推論只靠一個二進位加模型檔,無 Python 依賴,讓部署與嵌入式整合簡化許多


    適合誰用:4 個具體場景

    1. 公司會議錄音 → 自動逐字稿 + 誰講了什麼

    適合:產品經理、工程主管、專案管理。

    操作路線:

    1. 用任意錄音工具錄下整場會議(建議單軌錄音即可)。
    2. 丟給 vibevoice.cpp,輸出成文字 + 語者標註。
    3. 再加工:
    4. 手動整理重點;或
    5. 丟進本地 LLM(如 ollama 上的 Llama 3)做摘要。

    好處:不必把敏感會議內容丟上雲端,也不必自己搭一整套 ASR 服務。


    2. 內網客服錄音分析

    適合:客服主管、合規/法務、營運分析。

    做法:

    1. 將客服中心錄音批次輸出成檔案(常見為 WAV/MP3)。
    2. 用 vibevoice.cpp 跑 ASR + 語者分離,取得客服與客戶逐字對話。
    3. 輸出文字再交給內網數據分析或 NLP 模組做:
    4. 關鍵字搜尋(是否有爭議用語、是否說明退款規則等)
    5. 投訴分析(常見問題、情緒偏負面段落)。

    3. 在自己產品裡內建語音輸入 / 語音輸出

    適合:SaaS 產品、內部工具、遊戲或交互式應用開發者。

    可行玩法:

    • 用 ASR 做語音輸入:
    • 使用者對麥克風說話 → 即時轉文字 → 傳給你原有的系統邏輯。
    • 用 TTS 做語音輸出:
    • 系統產生訊息 → 用 vibevoice.cpp 合成語音 → 播放給使用者聽。

    因為有 C ABI,你可以:

    • 在 C/C++ 專案直接連結
    • 在 Rust/Go 透過 FFI 呼叫
    • 在 Node.js 透過 node-ffi 或自寫 native addon 包一層

    4. 做一個完全離線的語音助手

    適合:喜歡 DIY 的工程師、Maker、隱私敏感場景。

    粗略架構:

    1. 麥克風輸入 → vibevoice.cpp ASR → 文字指令
    2. 文字指令 → 本地 LLM(例如 LocalAI / Ollama)→ 回覆文字
    3. 回覆文字 → vibevoice.cpp TTS(可用自建 voice clone)→ 喇叭播出

    整條鏈路都在本機或內網,沒有任何雲端依賴。


    怎麼開始:最短路徑從 0 到能跑

    官方 repo:https://github.com/mudler/vibevoice.cpp

    1. 下載二進位檔(最快上手)

    1. 打開 GitHub Releases:https://github.com/mudler/vibevoice.cpp/releases
    2. 依自己的平台下載對應壓縮檔,例如:
    3. vibevoice-darwin-arm64.zip(Apple Silicon)
    4. vibevoice-linux-x86_64.zip
    5. vibevoice-windows-x86_64.zip
    6. 解壓縮後,裡面會有:
    7. 主程式二進位,例如 vibevoice
    8. 範例模型 / 語音配置(依版本而定)

    在 Linux/macOS,給執行權限:

    chmod +x vibevoice
    

    2. 用 CMake 自行編譯(需要客製或特定後端時)

    環境需求:

    • CMake
    • C++17 編譯器(gcc / clang / MSVC)
    • 選用:CUDA / Vulkan / Metal SDK

    基本編譯步驟(以 Linux/macOS 為例):

    git clone https://github.com/mudler/vibevoice.cpp.git
    cd vibevoice.cpp
    mkdir build && cd build
    cmake .. -DCMAKE_BUILD_TYPE=Release
    cmake --build . --config Release
    

    完成後,build/ 底下會出現可執行檔(名稱以實際 repo 為準)。


    3. 第一次跑 ASR:把一段錄音轉成逐字稿

    假設你已經有:

    • 主程式 vibevoice
    • 已下載好的 ASR 模型 model.gguf(官網會提供下載連結)
    • 一段錄音 meeting.wav

    執行(命令格式可能會隨版本略有不同,請以 --help 為主,這裡示範典型用法):

    ./vibevoice \
      --mode asr \
      --model model.gguf \
      --input meeting.wav \
      --output transcript.txt \
      --diarization
    

    跑完後,你會拿到一個 transcript.txt,裡面包含時間戳與說話者標記。


    4. 第一次跑 TTS:從文字合成語音

    準備:

    • TTS 模型 tts-model.gguf
    • 一個 voice 檔(可用官方 sample voice,例如 voice-en.gguf)

    命令範例:

    ./vibevoice \
      --mode tts \
      --model tts-model.gguf \
      --voice voice-en.gguf \
      --text "你好,這是 vibevoice.cpp 的測試。" \
      --output out.wav
    

    成功後你會得到一個 out.wav,用任意播放器就能聽見合成結果。


    5. 準備 30 秒聲音做 voice clone(概念流程)

    1. 錄一段約 30 秒的清晰朗讀(內容隨意,重點是發音自然、環境安靜)。
    2. 取得對應的 voice 訓練權重,依官方 README 指示執行:

    bash
    python scripts/convert_voice_to_gguf.py \
    --input your_voice.pt \
    --output your_voice.gguf

    1. 之後在 TTS 命令中改成:

    bash
    --voice your_voice.gguf

    即可以你的聲音合成語音。


    6. 怎麼嵌到自己的專案:用 C ABI 呼叫

    vibevoice.cpp 提供 C 語言 ABI,因此只要能呼叫 C 函式的語言,都能整合。

    簡化示意(實際函式名稱請以官方 include/ 中的 header 為準):

    #include "vibevoice.h"
    
    int main() {
        vv_context *ctx = vv_init("model.gguf");
    
        vv_asr_params params = {0};
        params.diarization = 1;
    
        vv_result result = vv_run_asr(ctx, "meeting.wav", &params);
    
        // 在這裡處理 result.text / result.segments
    
        vv_free_result(&result);
        vv_free(ctx);
        return 0;
    }
    

    在其他語言(例如 Rust、Go)你可以:

    • 透過 extern "C" 聲明這些函式
    • 用 FFI 封裝成 idiomatic 的 API

    這樣你的應用程式就能直接呼叫 vibevoice.cpp,無需啟動額外的 HTTP 服務或 Python 進程。


    小結:什麼時候該試試 vibevoice.cpp?

    如果你符合以下任一條,很值得花一個下午跑起來:

    • 想在本地處理會議、客服錄音,不想把資料丟到雲端
    • 想做一個離線語音助手或內網語音介面
    • 需要在產品裡嵌入 TTS / ASR,但又不想綁特定雲服務
    • 想要一套 CPU/GPU 都能跑、無 Python 推論依賴的語音引擎

    從 Releases 下載二進位、跑一次 ASR 和 TTS,大概半小時內就能完成。之後你就有一顆可嵌入任何系統的本地「語音核心」。

    🚀 你現在可以做的事

    • 打開 GitHub Releases,下載適合自己平台的 vibevoice.cpp 二進位並跑一次 ASR 測試
    • 錄一段約 30 秒的個人聲音,照 README 用 convert_voice_to_gguf.py 做一次 voice clone
    • 在你現有的工具(例如內部專案或腳本)中,嘗試用命令列或 C ABI 把 vibevoice.cpp 串成一個簡單語音流程