全部產品
Search
文件中心

Realtime Compute for Apache Flink:向量化結果緩衝

更新時間:Sep 22, 2026

本文介紹如何為 AI_EMBED 配置外部緩衝表,複用相同輸入文本的向量化結果,從而減少模型調用、降低延遲與成本。

背景資訊

AI_EMBED 通過 CACHE_TABLE 參數指定一張外部表格作為向量化結果的持久化緩衝。運行時按以下邏輯工作:

  • 命中緩衝:非同步 lookup 命中後直接返回結果,跳過模型調用。

  • 未命中緩衝:非同步 lookup 未命中時調用模型計算向量,返回結果,並非同步回寫緩衝表。

對相同輸入文本的重複請求,該機制可避免重複調用模型服務。

使用限制

建立緩衝表

緩衝表的主鍵類型需與 CACHE_KEY 類型一致。

顯式指定 Key 模式

主鍵類型與 CACHE_KEY 指定列的類型保持相容。以源表中 cache_key 是 INT 類型為例:

CREATE TABLE `fluss`.`default`.`ai_cache` (
  cache_key   INT NOT NULL,
  embedding   ARRAY<FLOAT>,PRIMARY KEY (cache_key) NOT ENFORCED
);

自動產生 Key 模式

主鍵固定為 STRING 類型,用於儲存 SHA256 雜湊值:

CREATE TABLE `fluss`.`default`.`ai_cache_sha` (
  cache_key   STRING NOT NULL,
  embedding   ARRAY<FLOAT>,PRIMARY KEY (cache_key) NOT ENFORCED
);

文法

AI_EMBED(
  MODEL       => MODEL <MODEL NAME>,
  INPUT       => <INPUT COLUMN NAME>
  [, DIMENSION   => <DIMENSION VALUE>]
  [, CACHE_TABLE => TABLE <catalog>.<db>.<table>
     [, CACHE_KEY => DESCRIPTOR(<column>)]]
  [, CONFIG      => MAP[...]]
)

參數

參數

是否必填

說明

MODEL

是

模型引用,詳情參見WITH參數。

INPUT

是

輸入文本列。

CACHE_TABLE

否

緩衝表引用。文法為 TABLE <catalog>.<db>.<table>。

CACHE_KEY

否

緩衝 Key 列。文法為 DESCRIPTOR(<column>)。未指定時,系統自動產生 SHA256 合成 Key。

CONFIG

否

運行時配置。

CACHE_KEY 模式說明

(推薦)顯式指定:直接以輸入表的某列值作為 lookup Key。在資料本身有唯一 key 標識的情況下推薦顯式指定。

CACHE_KEY => DESCRIPTOR(cache_key)

自動產生:不傳 CACHE_KEY 時,系統按以下規則產生 Key:

-- 不傳 CACHE_KEY 時,系統自動產生:
-- key = LOWER(SHA256(model_id || ':' || dimension || ':' || input_text))
CACHE_TABLE => TABLE `fluss-ql`.`default`.`ai_cache1`

該模式存在運行時計算 SHA256 的開銷,但可自動保證「模型 + 維度 + 輸入文本」對應唯一 Key。

效能調優

調優參數

SET 'table.exec.async-ml-predict.max-concurrent-operations' = '100';
SET 'table.exec.async-ml-predict.output-mode' = 'ALLOW_UNORDERED';
SET 'table.exec.async-ml-predict.timeout' = '120s';

參數說明

參數

預設值

說明

max-concurrent-operations

10

並行查緩衝或調用模型的最大記錄數。調大可提升吞吐;過大則可能壓垮模型服務或導致記憶體佔用過高。

output-mode

ORDERED

輸出順序模式。

  • ORDERED:嚴格按輸入順序輸出,適用於下遊依賴順序的 Join、Window 情境。

  • ALLOW_UNORDERED:先完成先輸出,推薦 INSERT-only 流使用。

timeout

3min

lookup 與 predict 總耗時的上限。設定過小會導致正常 miss 被逾時中止。

(推薦)ALLOW_UNORDERED 收益較大,原因如下:

  • Cache Hit 通常一次 Lookup 即可完成;Cache Miss 需額外調用一次模型。

  • ORDERED 模式下,一個 Miss 會阻塞後續所有 Hit 的輸出。

  • ALLOW_UNORDERED 模式下,Hit 立即輸出,無需等待前面的 Miss 完成。

說明

僅 INSERT-only 流會實際啟用 ALLOW_UNORDERED。帶 Retract 的流即使設定該值也會回退到 ORDERED。

監控指標

作業運行時,可通過 Flink Metrics 觀察緩衝效果。

指標名

含義

關注點

ai_function_cache.cache_hit

快取命中次數

命中率 = hit / (hit + miss)。

ai_function_cache.cache_miss

緩衝未叫用次數

持續偏高說明緩衝未預熱或 Key 不穩定。

ai_function_cache.writeback_attempt

回寫嘗試次數

數值應接近 miss 數。

ai_function_cache.writeback_skipped_null_output

因模型返回 null 而跳過的回寫次數

數值偏高說明模型異常。

完整樣本

Fluss主鍵表示例:

-- 提前建好 緩衝表 (Fluss)
CREATE TABLE `fluss`.`default`.`embedding_cache` (
  cache_key   STRING NOT NULL,
  embedding   ARRAY<FLOAT>,
  PRIMARY KEY (cache_key) NOT ENFORCED
);

使用 Fluss 主鍵表作為緩衝,以 ALLOW_UNORDERED 模式提升吞吐。

-- 調優參數
SET 'table.exec.async-ml-predict.max-concurrent-operations' = '100';
SET 'table.exec.async-ml-predict.output-mode' = 'ALLOW_UNORDERED';

-- 建立模型
CREATE TEMPORARY MODEL embedding_model
  INPUT (text STRING)
  OUTPUT (embedding ARRAY<FLOAT>)
WITH (
  'provider' = 'openai-compat',
  'task' = 'embeddings',
  'model' = 'text-embedding-v4',
  'dimension' = '1024'
);

-- 業務查詢
INSERT INTO result_sink
SELECT id, content, embedding
FROM source_table, LATERAL TABLE(AI_EMBED(
  MODEL       => MODEL embedding_model,
  INPUT       => content,
  CONFIG      => MAP['async', 'true'],
  CACHE_TABLE => TABLE `fluss`.`default`.`embedding_cache`
));