SocialHub.AI

開發者中心 · 工程參考

Consumer World Model

決策節點下的模型層:每個品牌的行為模型(描述每個成員行為的事件序列模型)以及一個數位孿生層,用於向前運行該模型(反事實模擬和合成研究小組)。本頁涵蓋整合商實際可以操作的內容:為其提供資料的事件、決定其是否生效的門檻、其輸出的介面以及驅動該小組的MCP工具。

使用下方受管制的唯讀 REST 端點或 MCP 工具進行單一使用者預測。後續行為預測結果和個人化購買視窗共享回應,並進行明確的可用性和權限檢查。事件仍然透過常規整合介面進入;其他輸出則顯示在細分、使用者畫像、相似使用者、發送時間優化和合成面板中。

下一行為、購買窗口與整體需求趨勢

一次會員預測同時返回下一行為與個人購買窗口;品牌融合頭可用時,將個人訊號與整體需求趨勢結合。

互動範例

一個消費者,一份統一預測。

所有狀態與數值均為合成範例,不代表即時預測或工作空間可用狀態;不會傳送客戶資料。

選擇範例狀態
部分可用

已有行為預測仍可返回。品牌融合頭完成訓練並通過驗證前,個人購買窗口保持不可用。

下一步可能做什麼?

一份最終分布,涵蓋本範例的4個支援事件;下一行為概率尚未經校準。

下一事件概率
購買37%
造訪會員入口28%
點擊郵件21%
核銷優惠券14%
為什麼有些事件沒有概率?

「傳送郵件」屬於輸入脈絡,不是預測目標,因此概率為 null。不支援或沒有資料涵蓋的事件同樣保持不可用。

未來多久內可能購買?

CWM 個人訊號 + TimesFM 品牌需求趨勢。

7 天內
不可用
30 天內
不可用
90 天內
不可用

預測窗口內至少購買一次的累計概率。三個窗口之間、窗口與行為分布之間均不能相加。

把同一份結果接入工作流程

一次會員請求同時返回 distribution 與 purchaseWindows。

查看 API / MCP 呼叫
curl --request GET \
  "https://YOUR_API_HOST/api/v2/cwm/members/YOUR_MEMBER_UUID/next-behaviors" \
  --header "Authorization: Bearer YOUR_API_KEY"

請替換 API 網域、會員 UUID 與工作空間 API 金鑰。

所需權限 · predictions:read 可讀取行為;額外授予 metrics:read(或 *)後,可在模型就緒時取得購買窗口。

查看回應節選

僅為合成範例節選。品牌模型回應還包含完整事件目錄及涵蓋資訊;公共先驗參考採用獨立的6類詞表。

{
  "predictionKind": "next_event",
  "unit": "probability_0_1",
  "status": "degraded",
  "distribution": {
    "status": "ok",
    "vocabulary": "member_event",
    "normalization": "conditional_on_supported_events",
    "calibrated": false,
    "rows": [
      {
        "key": "purchase.completed",
        "label": "Purchase",
        "probability": 0.37,
        "rank": 1,
        "availability": "predicted"
      },
      {
        "key": "portal.visited",
        "label": "Portal visit",
        "probability": 0.28,
        "rank": 2,
        "availability": "predicted"
      },
      {
        "key": "email.clicked",
        "label": "Email clicked",
        "probability": 0.21,
        "rank": 3,
        "availability": "predicted"
      },
      {
        "key": "coupon.redeemed",
        "label": "Coupon redeemed",
        "probability": 0.14,
        "rank": 4,
        "availability": "predicted"
      },
      {
        "key": "email.sent",
        "label": "Email sent",
        "probability": null,
        "rank": null,
        "availability": "context_only"
      }
    ]
  },
  "purchaseWindows": {
    "unit": "probability_0_1",
    "probabilities": {
      "7": null,
      "30": null,
      "90": null
    },
    "calibrated": false,
    "envelope": {
      "status": "unavailable",
      "backend": "cwm-timesfm-2.5",
      "reasonCodes": [
        "fusion_not_trained"
      ]
    }
  },
  "reasonCodes": [
    "fusion_not_trained"
  ]
}

合成資料 · TimesFM 2.5

探索逐日需求趨勢

基於128天合成歷史生成的預測範例,對比近期需求走勢、未來逐日預測和分位數範圍。

預測窗口

合成需求單位

近期日均需求
20.0
預測日均需求
20.1
預測累計需求
604.3
歷史 · 最近28天預測值
歷史需求、未來逐日預測和q10–q90分位範圍深藍線為最近28天歷史,綠線為所選窗口的預測,陰影為q10–q90分位範圍。可透過日期滑桿查看每天的預測。
第 1天 · 2026-10-05
預測值
22.9
q10
22.8
q90
23.0
查看每日預測資料
日期(UTC)預測值q10–q90
2026-10-0522.922.8–23.0
2026-10-0621.321.2–21.4
2026-10-0718.718.6–18.8
2026-10-0817.117.0–17.1
2026-10-0917.717.6–17.7
2026-10-1020.020.0–20.1
2026-10-1122.322.3–22.4
2026-10-1222.922.9–22.9
2026-10-1321.321.2–21.3
2026-10-1418.718.6–18.7
2026-10-1517.117.0–17.2
2026-10-1617.717.6–17.7
2026-10-1720.019.9–20.1
2026-10-1822.422.3–22.4
2026-10-1922.922.8–23.0
2026-10-2021.321.2–21.4
2026-10-2118.718.6–18.7
2026-10-2217.117.0–17.1
2026-10-2317.717.6–17.7
2026-10-2420.019.9–20.0
2026-10-2522.322.3–22.4
2026-10-2622.922.8–22.9
2026-10-2721.321.2–21.3
2026-10-2818.718.6–18.7
2026-10-2917.117.0–17.2
2026-10-3017.717.6–17.7
2026-10-3120.020.0–20.1
2026-11-0122.422.3–22.4
2026-11-0222.922.8–22.9
2026-11-0321.321.2–21.3
下載範例資料(JSON) ↓

本範例輸入為合成資料,預測由真實TimesFM 2.5權重生成。預測起點為2026-10-05(UTC),演示日期固定;分位數覆蓋率尚未經校準。數值不代表客戶實際需求或個人購買概率。

一份完整的下一行為概率

一次獲得一份最終概率分布與排序。通過評測的品牌模型優先,最多支援23類有資料覆蓋的目標;品牌模型不可用時,內部公共先驗模型彙總成一份6類參考分布。不支援及僅作上下文的事件保持不可用。

7 / 30 / 90天購買窗口

自動包含在同一份會員回應中:租戶獨立的輕量融合頭結合 CWM 訊號與 TimesFM 品牌趨勢。合格融合頭直接輸出;缺少訓練或評測時,購買窗口保持不可用,已有行為預測仍可返回。

品牌與品類的逐日預測

TimesFM 2.5 服務已設定且逐日歷史完整時,可預測未來最多90天的銷售額、訂單數或商品銷量,並提供預測值和9個分位數。

如何理解這些結果

下一行為概率在支援的候選類別中合計為100%,尚未經校準。購買窗口另行預測7/30/90天內至少購買一次的累計概率,不與行為類別一起正規化。行為分布未按靜默時長調整;公共先驗參考尚未通過工作區驗證。

需求分位數表達整體不確定性,不是個人購買區間,覆蓋率尚未經校準。缺失資料保持不可用;在工作區評測完成前,不宣稱精度提升。

整合細節與可用條件
# Bearer API key; predictions:read
GET /api/v2/cwm/capabilities
GET /api/v2/cwm/members/{id}/next-behaviors

# metrics:read additionally enables purchaseWindows in next-behaviors
# predictions:read AND metrics:read for standalone trend/windows
GET /api/v2/cwm/trends?metric=gmv&horizon_days=30
GET /api/v2/cwm/members/{id}/purchase-windows

# Read-only MCP equivalents
cwm_get_forecast_capabilities
cwm_predict_next_behaviors
cwm_forecast_aggregate_trend
cwm_predict_purchase_windows

購買機率使用 0 到 1 的單位和累積單調視窗。在訓練和驗證之前,反應包含機率:{"7":null,"30":null,"90":null}並已校準: false。 現存的 CWM 0-100 的總體評分保持不變。總預測回傳一個點以及每個完整 UTC 日的 q10 至 q90;缺少的每日區間不會填入零。類別名稱需要 catalog_gmv 或者 units_sold;草稿輸入指標已公開。租用戶和成員授權仍由伺服器端完成。準備情況可區分。 service_unavailable, awaiting_training, awaiting_validation 準備就緒。 TimesFM 2.5 權重使用 Apache 2.0。

後續行為反應的使用 predictionKind: next_event 單位: probability_0_1其中一個回應包括分佈和 purchaseWindows個別專家的結果僅供內部參考。當指標存取權限允許時,購買融合功能將自動啟用。經過驗證的租戶頭檔提供 7/30/90 天的累計機率;缺少權限、培訓、驗證或輸入將導致所有視窗失效。 null 並有明確的理由。可用的行為預測仍然清晰可讀。這些視窗不會與下一事件分佈相加。品牌模型的行包含所有 48 個標準事件:26 個是消費者行為,39 個進入序列詞彙表,23 個是預測目標上限。只有由活躍的、已評估的生成支持的候選對象才會獲得機率;所有其他行都有機率: null 以及明確的可用性。傳統的輸入頻率覆蓋率作為語料庫存在性證據較弱,無法驗證來源被屏蔽的標籤目標。新的快照使用來自優化器訓練視窗的正面目標,排除驗證成員和被封鎖的行。最終分佈包括排名, entropyBits, retainedModelMass, coverageBasis, modelVersion 並已校準: false直接使用現有的、經過評估的品牌模型,無需請求其他專家輸出。否則,有效的公開先驗分佈將在內部進行等值平均,形成一個降級的 pv / fav / cart / buy / rmcart / buy_disc 參考。聚合區分 single_tenant_model 來自 uniform_valid_experts詞彙表標識候選鍵空間。這兩個詞彙表永遠不會混合。統一參考並非學習到的多類門,也未經租戶驗證;公開的類訓練覆蓋率未經驗證。四捨五入為零質量並不能證明缺少類訓練。此端點需要 predictions:read; purchaseWindows 另外還需要 metrics:read 或 *。如果沒有指標權限,購買組件報告將無法顯示。 metrics_scope_required 不進行任何指標或融合調用。僅當兩個已取得的元件皆正常運作時,狀態才為正常;對於部分/參考結果,狀態降級;當兩個元件皆不正常運作時,狀態不可用。在進行個人外部處理之前,會重新檢查儲存存取權限和即時處理資格;證據不足的情況仍然不可用。一個請求共享其實時數據。 CWM 在行為和購買方面進行內部指紋識別。

1 · 其資料來源

該模型基於您的整合已產生的成員事件流進行訓練—— REST API v2(訂單、會員)、網站和入口網站追蹤、POS/收據採集、會員積分和優惠券活動。事件傳遞 受策略防火牆約束的目錄 在他們能夠進入訓練之前;防火牆是在流程中強制執行的,而不是透過約定俗成的方式。

已確認:行為事件

購買記錄、收據、積分取得/兌換、會員等級變更、優惠券領取/兌換、郵件開啟/點擊、推播通知開啟、入口網站存取/點擊、門市簽到。所有事件類型均明確新增至目錄中—新事件類型不會自動新增。

禁止:回饋和內容

模型本身所傳回的任何內容(包括其標籤和評分)均被排除在外-模型絕不能從自身的產出中學習。訊息內容和自由文字永遠不會進入訓練集:模型學習的是成員點擊了什麼,而不是訊息的具體內容。

禁止訪問:受限會員

受處理限制(GDPR 第 18 條)的成員將被排除在端到端訓練之外,並且被刪除成員的資料(包括其嵌入)將作為刪除機制的一部分被移除。

對於整合商來說,實際結果是:您的事件來源越豐富、越乾淨(正確的成員資格解析、誠實的時間戳記),模型就越好 — 沒有單獨的「訓練上傳」。請參閱REST API 和網路追蹤。

2 · 誠信之門與服務謂詞

品牌的模型是針對每個租戶進行確定性訓練的(相同數據 ⇒ 相同模型,版本化),並且只有在超越該品牌自身預留數據的透明基線後才會 提供服務。下游消費者不會直接讀取模型-他們透過一個單一的服務謂詞:

serve = verified_win ∧ not_paused ∧ not_stale

如果任何環節失敗——模型尚未獲得認可、品牌暫停評分或模型已過時——所有消費者都會回退到玻璃盒預測模型(或在相似受眾的情況下,回退到誠實的空狀態)。所有資料都不會被零填充,也不會進行任何偽裝:沒有嵌入的成員將由回退路徑提供服務,而不會被填充到模型中。

品牌生命週期

正在收集數據

歷史數據不足以進行誠實的訓練—沒有任何幫助

每週對比

接受過培訓,正在接受基於真實情況的基準測試

積極的

超越基準-嵌入和預測服務

已暫停/過期

評分停止或模型老化-自動回退

3 · 輸出及其呈現位置

以下成員和細分市場介面中提供了三種現有的輸出類型。使用上方受管制的 REST 或 MCP 預測介面,即可實現統一的下一事件分發和購買視窗。

會員嵌入

每個成員的行為指紋,從其完整的事件序列中學習。支持最近鄰相似性分析:每個有行為的成員都有一個行為指紋-無需標籤。

下一個事件機率

每位會員的購買緊迫性和流失緊迫性(0-100),會根據其行為進行更新。這些資訊會以細分條件的形式呈現,例如“購買緊迫性(預測下次購買時間,0-100)”,並顯示在會員個人資料中。

按成員計時

根據每位會員本身的節奏,預測其下次購買的預期時間窗口和活躍時段。

4 · 駕駛合成面板越過MCP

您的AI代理可以透過受控的MCP伺服器操作數位孿生研究小組。以下四個面板工具(原文摘自即時清單)與上方唯讀預測工具並列:

list_synthetic_scenarios

((無))

列出合成面板模擬場景,並註明每個場景的真實可用性邊界、置信上限和輸入欄位。請先調用工具選擇類型。需要 metrics:read 權限。

run_synthetic_panel

(segment_id、kind、fields)

運行合成面板:對特定群體的去識別化數位孿生體進行刺激反應,產生客觀的趨勢性報告(而非絕對真實數據)。傳回一個用於輪詢的 run_id。每日運行次數上限為 50 個孿生體。需要 synthetic:write 模組。

get_synthetic_report

(run_id)

閱讀這份凍結的誠實報告,了解合成面板運行情況——方向性解讀、置信上限、抑制標誌、主題——或 blockReason 如果尚未準備就緒。需要 metrics:read.

get_synthetic_calibration

((無))

品牌合成面板校準(過去合成預測與實際狀況的命中率;null,直到有回測資料為止)。需要 metrics:read 權限。

典型流程

  1. 1. list_synthetic_scenarios → 選擇一種類型 + 閱讀其可用性邊界
  2. 2. run_synthetic_panel(segment_id, kind, fields) → run_id // 需要 synthetic:write
  3. 3. get_synthetic_report(run_id) → 定向閱讀 · 信賴上限 · 抑制 · 主題 — 或 blockReason
  4. 4. get_synthetic_calibration() → 您的品牌命中率與實際情況比較(null 直到有回測資料為止)

設計合約需遵守以下規定:運行次數有限制(每日運行次數上限,每次運行≤50個雙胞胎);報告是 方向性數字,而非絕對數字;如果某次運行未能通過誠信檢查(例如小組崩潰、阿諛奉承、樣本量過小),則會返回一個 blockReason 或使用抑制標誌而不是令人滿意的結果——將這些視為最終結果,不可重試。無論是由人還是您的代理啟動運行,都適用相同的限制和規則。設定、身份驗證和範圍: MCP 整合指南.

5 · 可建造的保證

按品牌隔離

每個租戶一個模型,僅使用該租戶的成員進行訓練。品牌之間不會進行任何形式的數據共享。

確定性且版本化

相同的資料產生相同的模型,每個分數都可追溯到生成它的模型版本。

擦除完成

成員擦除會刪除其訓練資料並將其作為刪除交易的一部分嵌入,而不是按照清理計劃進行。

清除過期內容

過期的嵌入內容會按計畫清除,過時的模型會自動停止投放。