全部產品
Search
文件中心

Realtime Compute for Apache Flink:Python DataFrame API 參考

更新時間:Sep 30, 2026

Python DataFrame API 為您提供 DataFrame 風格的 Python API 介面,用於編寫 Flink 作業。其中包括篩選、投影、串連、彙總等基本 API,讓您可以用傳統關係代數的方式組織資料處理邏輯;同時,DataFrame API 支援使用 Python 編寫使用者自訂函數,實現標準運算元難以覆蓋的特定商務邏輯和資料操作;此外,DataFrame API 提供 AI/LLM 功能,讓您在資料處理流程中直接接入大模型服務,並以開箱即用的方式調用分類、情感分析、抽取、翻譯、摘要、向量產生等專用 AI 函數。本文為您介紹支援的 API,供您開發作業參考。完整的 API 文檔請參見 PyFlink DataFrame。

DataFrame 基本操作

以下表格匯總了 DataFrame 上的核心操作。

API 類型

API 詳情

構造 / 建立

from_table、from_pandas、from_arrow、from_dict、from_records、range

屬性

schema、columns

投影 / 列操作

select、with_column、with_columns、drop_columns、rename_columns

過濾

filter

彙總

group_by、agg

串連 / 合并

join、join_asof、join_lateral

行映射

map、map_batches、flat_map

展開

explode

去重

drop_duplicates

集合運算

union、union_all、minus、minus_all、intersect、intersect_all

限制 / 分頁

limit、offset、head

分區

rebalance

管道

pipe

空值處理

drop_null、drop_nan、fill_null、fill_nan

輸出 / 收集

to_table、to_pandas、collect、iter_rows、iter_batches

調試 / 執行計畫

explain

SQL

sql

運算式輔助函數

函數

說明

col

建立列參考資料表達式

lit

建立字面量運算式

資料類型

DataType 用於描述 DataFrame 列的類型。

類型分類

方法

布爾

DataType.bool

整數

DataType.int8、DataType.int16、DataType.int32、DataType.int64

浮點 / 定點

DataType.float32、DataType.float64、DataType.decimal

字串

DataType.string、DataType.fixed_size_string

二進位

DataType.binary、DataType.fixed_size_binary

日期 / 時間

DataType.date、DataType.time、DataType.timestamp、DataType.timestamp_ltz

複合類型

DataType.list、DataType.map、DataType.struct

特殊類型

DataType.null、DataType.variant

多模態類型

DataType.tensor、DataType.image

可空性修飾

DataType.not_null、DataType.nullable

DataType 可用於為資料來源指定 schema、指定 UDF 輸出類型等情境。例如,使用 DataType 為 Kafka 資料來源指定 schema:

import pyflink.dataframe as pf
from pyflink.dataframe import DataType

df = pf.read_kafka(
    "localhost:9092",
    topic="user_events",
    schema={
        "user_id": DataType.string(),
        "event_type": DataType.string(),
        "amount": DataType.decimal(10, 2),
        "tags": DataType.list(DataType.string()),
        "event_time": DataType.timestamp_ltz(3),
    },
    format="json",
    startup_mode="earliest-offset",
)

DataType.tensor 支援聲明變長張量。在 UDF 中,可使用內建方法將變長張量與 Numpy ndarray 互轉:

from pyflink.dataframe.tensor import variable_tensors_to_arrow

result_type = DataType.struct({
    "id": DataType.int64(),
    # 不指定 shape,表示變長張量
    "tensor": DataType.tensor("float32"),
})

def transpose_batch_tensor(batch):
    # 直接調用to_numpy()將變長張量列轉成object ndarray;
    # 每個元素是獨立ndarray,shape可以不同
    tensors = batch["tensor"].to_numpy()

    transposed = [
        None if tensor is None else tensor.T
        for tensor in tensors
    ]

    return {
        "id": batch["id"],
        # 將變長 ndarray 列轉換回 Arrow 變長張量列
        "tensor": variable_tensors_to_arrow(
            transposed,
            dtype="float32",
        ),
    }
說明

變長張量自 VVR 11.9.preview.1 起支援。

I/O 讀寫

DataFrame 提供了豐富的資料來源讀寫介面,您可以方便地讀寫常見的資料來源,也可以使用 read_generic 或 write_generic 函數調用其他已支援的連接器支援概覽或自訂連接器讀寫資料。

資料讀入

資料來源

API

Parquet 檔案

read_parquet

JSON 檔案

read_json

Kafka

read_kafka

MaxCompute (ODPS)

read_odps

Paimon

read_paimon

SLS (Log Service)

read_sls

Hologres

read_hologres

Milvus

read_milvus

視訊框架

read_video_frames

通用 / 自訂連接器

read_generic

資料輸出

資料目標

API

Parquet 檔案

write_parquet

JSON 檔案

write_json

Kafka

write_kafka

MaxCompute (ODPS)

write_odps

Paimon

write_paimon

SLS (Log Service)

write_sls

Hologres

write_hologres

Milvus

write_milvus

Print

write_print

自 VVR 11.9.preview.1 起支援。

通用 / 自訂連接器

write_generic

當需要在同一個作業中進行多次資料輸出時,可以使用 create_statement_set 建立 StatementSet,統一執行多個輸出函數。

使用 Catalog

DataFrame API 可以使用 Catalog,並從 Catalog 表讀寫資料。

API

說明

create_catalog

建立 Catalog

get_catalog

擷取登入的 Catalog 對象

use_catalog

切換當前 Catalog

get_current_catalog

擷取當前 Catalog

list_catalogs

列舉 Catalog

use_database

切換當前 Database

get_current_database

擷取當前 Database

list_databases

列舉當前 Catalog 下的 Database

read_catalog_table

讀取 Catalog 表為 DataFrame

write_catalog_table

將 DataFrame 寫入 Catalog 表

使用者自訂函數

自訂純量涵式 udf

自訂純量涵式將一行輸入資料處理為一個結果值,按執行方式可分為四類:

  • 同步行式 UDF:普通 Python 函數,每次處理一行。

  • 非同步行式 UDF:適合調用外部服務或執行 I/O 密集型邏輯,允許多行同時執行 I/O 操作,從而提升吞吐。

  • 同步向量 UDF:按批接收和返回資料,減少 Python 與 Flink 運行時之間的逐行調用開銷,適合純計算邏輯。

  • 非同步向量 UDF:兼顧批處理吞吐與非同步 I/O 並發。

註冊純量涵式

udf 裝飾器支援將 Python 函數註冊為 DataFrame 可用的純量涵式。

  • 介面名稱:udf。

    udf(
        func=None,
        *,
        return_dtype=None,
        deterministic=True,
        name=None,
        func_type=None,
        concurrency=None,
        batch_size=None,
        num_gpus=None,
        gpu_type=None
    )
  • 功能描述:將 Python 函數註冊為 DataFrame 可用的標量使用者自訂函數。支援註冊普通函數、async 函數、ScalarFunction / AsyncScalarFunction 子類及可調用類。

  • 入參

    參數名稱

    參數類型

    是否必填

    描述

    func

    Callable / Class

    否

    要封裝的 Python 函數、ScalarFunction 執行個體/子類或可調用類。若省略則返回裝飾器。

    return_dtype

    DataType / str / type

    否

    傳回型別。可以是 DataType 執行個體(如 DataType.int64())、Python 類型(如 int)或 SQL 類型字串(如 'BIGINT')。若省略則從函數傳回型別提示自動推斷。

    deterministic

    Boolean

    否

    函數是否是確定性。預設值為 True。

    name

    String

    否

    UDF 的名稱。若不指定則使用函數名。

    func_type

    String

    否

    執行格式,可選 "general"、"pandas"、"arrow"。若不指定則根據參數類型提示自動檢測。

    concurrency

    int

    否

    UDF 運算元的並行度。不同 concurrency 值的 UDF 會被拆分到獨立運算元。

    batch_size

    int

    否

    每批最大元素數,僅適用於批處理 UDF(pandas / arrow 模式)。

    num_gpus

    float

    否

    為該 UDF 申請的 GPU 數量(如 0.5、1)。設定後,該 UDF 會在獨立運算元中運行,不與其他 UDF 融合(包括其它 GPU UDF)。

    gpu_type

    String

    否

    GPU 類型。當指定 num_gpus 時必填。

  • 傳回值

    DataFrameUDFWrapper 對象,可在 with_column、with_columns、map、map_batches等操作中使用。

同步行式 UDF

在with_column或with_columns中使用

標量 UDF 接收一列或多列,返回一列。建議使用 Python 類型標註自動推斷傳回型別;也可以用 return_dtype 顯式指定。在定義 UDF 時,可以使用 concurrency 指定並發度。

自 VVR 11.9.preview.1 起支援使用 callable class 聲明 UDF,您可在 __init__和 __call__ 中定義 UDF 初始化和執行邏輯。

from pyflink.dataframe import col, udf

orders = pf.from_records(
    [
        (1001, 1, 99.9, "PAID"),
        (1002, 2, 35.5, "CREATED"),
        (1003, 1, 188.0, "PAID"),
        (1004, 3, 88.8, None),
    ],
    schema=["order_id", "user_id", "amount", "status"],
)

@udf
def normalize_status(status: str) -> str:
    if status is None:
        return "UNKNOWN"
    return status.strip().upper()

@udf(concurrency=32)
def order_tag(amount: float, status: str) -> str:
    """Takes multiple columns as input"""
    if status == "PAID" and amount is not None and amount >= 100:
        return "high_value_paid"
    return "normal"

@udf
class ModelPredictor:
    def __init__(self):
        # Initialization is executed on the task manager
        self._model = load_model()

    def __call__(self, amount: float) -> str:
        return self._model.predict(amount)

# with_column adds a single column
orders_with_status = orders.with_column(
    "status_norm", normalize_status(col("status"))
)

# with_columns adds multiple columns at once
orders_with_flags = orders.with_columns(
    status_norm=normalize_status(col("status")),
    tag=order_tag(col("amount"), col("status")),
)

# Use stateful UDFs
orders_with_predictions = orders.with_column(
    "prediction", ModelPredictor(col("amount"))
)
在map中使用

map 接收整行資料,返回新行。輸入行在函數中可按列名訪問;傳回型別可以用 DataType.struct 顯式聲明,也可以通過 TypedDict 傳回型別標註自動推導。您可直接將 Python 函數傳入 map,而無需使用 udf 裝飾器封裝。

使用 return_dtype 顯式聲明

def build_order_feature(row):
    amount = row["amount"] or 0.0
    return {
        "order_id": row["order_id"],
        "user_id": row["user_id"],
        "feature": f"{row['status']}:{'large' if amount >= 100 else 'normal'}",
    }

order_features = orders.map(
    build_order_feature,
    return_dtype=DataType.struct({
        "order_id": DataType.int64(),
        "user_id": DataType.int64(),
        "feature": DataType.string(),
    }),
)

使用 TypedDict 自動推導類型

from typing import TypedDict

class OrderFeature(TypedDict):
    order_id: int
    user_id: int
    feature: str

def build_order_feature_typed(row) -> OrderFeature:
    amount = row["amount"] or 0.0
    return {
        "order_id": row["order_id"],
        "user_id": row["user_id"],
        "feature": f"{row['status']}:{'large' if amount >= 100 else 'normal'}",
    }

order_features_typed = orders.map(build_order_feature_typed)

同步向量 UDF

在with_column或with_columns中使用

向量化 UDF 按批接收和返回資料,減少 Python 與 Flink 運行時之間的逐行調用開銷,適合純計算邏輯。支援 Pandas(pandas.Series)和 Arrow(pyarrow.Array)兩種格式,可以根據 UDF 中的計算邏輯按需選擇。可以通過 batch_size 控制每批大小。UDF 返回的行數需要和輸入行數相等。

Pandas 格式

import pandas as pd

@udf(return_dtype=DataType.float64(), concurrency=32, batch_size=64)
def scale_amount_pandas(amounts: pd.Series) -> pd.Series:
    return amounts * 100.0

orders_scaled_pandas = orders.with_column(
    "amount_scaled", scale_amount_pandas(col("amount")),
)

Arrow 格式

import pyarrow as pa
import pyarrow.compute as pc

@udf(return_dtype=DataType.float64(), concurrency=32, batch_size=64)
def scale_amount_arrow(amounts: pa.Array) -> pa.Array:
    return pc.multiply(amounts, 100.0)

orders_scaled_arrow = orders.with_column(
    "amount_scaled", scale_amount_arrow(col("amount")),
)
在map_batches中使用

map_batches可對整行進行向量化處理。batch_format="pandas" 時,函數輸入和輸出是 dict[str, pandas.Series];batch_format="arrow" 時,輸入和輸出是 dict[str, pyarrow.Array]。您可直接將 Python 函數傳入 map_batches,而無需使用 udf 裝飾器封裝。

Pandas 格式

def score_batch_pandas(batch: dict[str, pd.Series]) -> dict[str, pd.Series]:
    amount = batch["amount"].fillna(0.0)
    return {
        "order_id": batch["order_id"],
        "score": (amount / 100.0).clip(0.0, 1.0),
    }

order_scores_pandas = orders.map_batches(
    score_batch_pandas,
    batch_format="pandas",
    batch_size=1024,
    return_dtype=DataType.struct(
        {
            "order_id": DataType.int64(),
            "score": DataType.float64(),
        }
    ),
)

Arrow 格式

def score_batch_arrow(batch: dict[str, pa.Array]) -> dict[str, pa.Array]:
    amount = pc.if_else(pc.is_null(batch["amount"]), 0.0, batch["amount"])
    raw_score = pc.divide(pc.cast(amount, pa.float64()), 100.0)
    score = pc.if_else(
        pc.less(raw_score, 0.0),
        0.0,
        pc.if_else(pc.greater(raw_score, 1.0), 1.0, raw_score),
    )
    return {
        "order_id": batch["order_id"],
        "score": score,
    }

order_scores_arrow = orders.map_batches(
    score_batch_arrow,
    batch_format="arrow",
    batch_size=1024,
    return_dtype=DataType.struct(
        {
            "order_id": DataType.int64(),
            "score": DataType.float64(),
        }
    ),
)

非同步行式 UDF

非同步 UDF 允許多行同時執行 I/O 操作,從而提升吞吐,適合調用外部服務或執行 I/O 密集型邏輯。您可在with_column、with_columns 和 map 中調用非同步行式 UDF。

import asyncio

# Use in `with_column`
@udf(concurrency=32)
async def query_region(user_id: int) -> str:
    await asyncio.sleep(0.01)  # simulate async I/O
    return f"region_for_{user_id}"

orders_with_region = orders.with_column(
    "region", query_region(col("user_id")),
)

# Use in `map`
class OrderWithRegion(TypedDict):
    order_id: int
    region: str

async def enrich_order_region(row) -> OrderWithRegion:
    await asyncio.sleep(0.01)  # Mock async I/O
    return {
        "order_id": row["order_id"],
        "region": f"region_for_{row['user_id']}",
    }

orders_with_region = orders.map(enrich_order_region)

非同步向量 UDF

非同步向量 UDF 兼顧批處理吞吐與非同步 I/O 並發。可以通過 batch_size 控制每批大小。您可在with_column、with_columns 和 map_batches 中調用非同步向量 UDF。

# Use in `with_column`
@udf(return_dtype=DataType.string(), concurrency=32, batch_size=64)
async def batch_enrich(statuses: pd.Series) -> pd.Series:
    async def enrich_one(s):
        await asyncio.sleep(0.01)  # simulate async API call
        return f"enriched_{s}"
    tasks = [enrich_one(s) for s in statuses]
    results = await asyncio.gather(*tasks)
    return pd.Series(results)

orders_enriched = orders.with_column(
    "status_enriched", batch_enrich(col("status")),
)

# Use in `map_batches`
async def enrich_order_batch(
    batch: dict[str, pd.Series],
) -> dict[str, pd.Series]:
    async def query_region(user_id):
        await asyncio.sleep(0.01)  # 類比非同步 I/O
        return f"region_for_{user_id}"

    regions = await asyncio.gather(
        *(query_region(user_id) for user_id in batch["user_id"])
    )

    return {
        "order_id": batch["order_id"],
        "region": pd.Series(
            regions,
            index=batch["user_id"].index,
        ),
    }

orders_with_region = orders.map_batches(
    enrich_order_batch,
    batch_format="pandas",
    batch_size=64,
    concurrency=32,
    return_dtype=DataType.struct({
        "order_id": DataType.int64(),
        "region": DataType.string(),
    }),
)
說明

自 VVR 11.9.preview.1 起支援在 map 和 map_batches 中調用非同步 UDF。

自訂表格值函數 udtf

自訂表格值函數將一行輸入展開為任意行輸出,每行輸出可包括一列或多列結果。

註冊資料表值函式

udtf 裝飾器支援將 Python 函數註冊為 DataFrame 可用的資料表值函式。

  • 介面名稱:udtf。

    udtf(
        func=None,
        *,
        return_dtype=None,
        deterministic=True,
        name=None,
        concurrency=None,
        num_gpus=None,
        gpu_type=None
    )
  • 功能描述:將 Python 函數、TableFunction 子類/執行個體或可調用類註冊為 DataFrame 可用的資料表值函式。

  • 入參

    參數名稱

    參數類型

    是否必填

    描述

    func

    Callable / Class

    否

    要封裝的 Python 函數、TableFunction 執行個體/子類或可調用類。若省略則返回裝飾器。

    return_dtype

    DataType / str / type

    否

    每個輸出行的類型。多列輸出可使用 DataType.struct({...}) 或 TypedDict。

    deterministic

    Boolean

    否

    函數是否是確定性。預設值為 True。

    name

    String

    否

    UDTF 的名稱。若不指定則使用函數名。

    concurrency

    int

    否

    UDTF 運算元的並行度。

    num_gpus

    float

    否

    為該 UDTF 申請的 GPU 數量(如 0.5、1)。設定後,該 UDTF 會在獨立運算元中運行,不與其他 UDF 融合(包括其它 GPU UDF)。

    gpu_type

    String

    否

    GPU 類型。當指定 num_gpus 時必填。

  • 傳回值

    DataFrameUDTFWrapper 對象,可在 flat_map 或 join_lateral 中使用。

在join_lateral中使用

join_lateral會把 UDTF 結果追加到原始輸入行後面。預設刪除 UDTF 無輸出的輸入行,您可設定 ignore_empty=False 保留 UDTF 無輸出的輸入行。

from typing import Iterator, Tuple
from pyflink.dataframe import udtf

# Use type hint and .alias() to specify return types and column names
@udtf
def split_words(text: str) -> Iterator[Tuple[str, int]]:
    for word in text.split():
        yield word, len(word)

words_with_source = texts.join_lateral(
    split_words(col("text")).alias("word", "word_length"),
    ignore_empty=False,
)

# Or use return_dtype
@udtf(return_dtype=DataType.struct({
    "word": DataType.string(),
    "word_length": DataType.int32(),
}))
def split_words_with_length(text):
    for word in text.split():
        yield {"word": word, "word_length": len(word)}

words_with_detail = texts.join_lateral(
    split_words_with_length(col("text")),
)

在flat_map中使用

flat_map對每行調用 UDTF,結果只包含 UDTF 輸出資料行,不保留原始輸入列。您可直接將 Python 函數傳入 flat_map,而無需使用 udtf 裝飾器封裝。

from typing import Any, Dict, Iterator, TypedDict

# Use type hint with TypedDict to specify return types and column names
class Word(TypedDict):
    word: str
    length: int

def split_row(row: Dict[str, Any]) -> Iterator[Word]:
    for word in row["text"].split():
        yield {"word": word, "length": len(word)}

words = texts.flat_map(split_row)

# Or use return_dtype
def split_row_with_dtype(row):
    for word in row["text"].split():
        yield {"word": word}

words_with_dtype = texts.flat_map(
    split_row_with_dtype,
    return_dtype=DataType.struct({"word": DataType.string()}),
)

AI / LLM 函數

通過 df.llm 訪問器,DataFrame 提供了一系列內建 AI 函數。詳細 API 參考見 AI/LLM。

Provider 配置

使用 AI 函數前,需先註冊模型服務商(Model Provider)。

API

說明

set_model_provider

註冊一個模型 Provider

set_default_model_provider

設定預設 Provider(多 Provider 情境下使用)

list_model_providers

列舉登入的 Provider

支援的 Provider 類型:

Provider

適用情境

OpenAICompatProvider

OpenAI、DeepSeek、靈積(百鍊)等所有 OpenAI 相容介面

DashScopeProvider

阿里雲靈積(DashScope),支援多模態 Embedding

TritonProvider

NVIDIA Triton Inference Server

GenericProvider

用於使用登入的自訂 Model Provider

set_model_provider

  • 介面名稱:set_model_provider。

    set_model_provider(
        name_or_provider,
        provider=None,
        **options
    )
  • 功能描述:註冊一個全域 Model Provider 配置。支援三種調用方式:傳入 ModelProvider 執行個體、傳入名稱 + ModelProvider 執行個體、傳入名稱 + 關鍵字參數。註冊名稱必須唯一,重複註冊同名 Provider 會拋出 ValueError。

  • 入參

    參數名稱

    參數類型

    是否必填

    描述

    name_or_provider

    ModelProvider / String

    是

    ModelProvider 執行個體(自動以其 Provider identifier 註冊)或自訂名稱字串。

    provider

    ModelProvider

    否

    ModelProvider 執行個體,僅在第一個參數為名稱字串時使用。

    **options

    key=value

    否

    Provider 配置項,僅在第一個參數為名稱字串且未傳入 provider 時使用。當第一個參數傳入 openai-compat、dashscope或 triton時,建立對應的 provider,否則建立 GenericProvider。

  • 傳回值

    無。

  • 樣本

    # Option 1: pass a ModelProvider instance directly
    pf.set_model_provider(pf.OpenAICompatProvider(task="chat/completions"))
    
    # Option 2: custom name + ModelProvider instance (register multiple)
    pf.set_model_provider("chat", pf.OpenAICompatProvider(task="chat/completions"))
    pf.set_model_provider("embedding", pf.OpenAICompatProvider(task="embeddings"))
    
    # Option 3: name + keyword arguments
    pf.set_model_provider("dashscope", task="chat/completions")

通用調用

  • 介面名稱:predict。

    DataFrame.llm.predict(
        *input_cols,
        provider=None,
        model=None,
        output_type=None,
        cache_table=None,
        cache_key=None,
        config=None,
        **kwargs
    )
  • 功能描述:通用模型推理。將指定輸入列發送給模型,返回模型輸出資料行追加到 DataFrame 中。

  • 入參

    參數名稱

    參數類型

    是否必填

    描述

    *input_cols

    String

    是

    作為模型輸入的列名,可傳入多個。

    provider

    String

    否

    Provider 名稱。若不指定則使用預設 Provider(或唯一註冊的 Provider)。

    model

    String

    否

    模型名稱(如 "qwen3.6-plus")。

    output_type

    String / DataType

    否

    輸出類型。預設追加 output STRING;傳入 SQL 類型字串或非 Struct DataType 追加名為 output 的單列;傳入 DataType.struct({...}) 可追加自訂欄。

    cache_table

    String

    否

    用於緩衝預測結果的 Fluss 表名。

    cache_key

    String / List[String]

    否

    緩衝鍵列。設定該參數時必須同時設定 cache_table。

    config

    Dict

    否

    運行時配置選項。

    **kwargs

    key=value

    否

    覆蓋本次調用所使用的 Model Provider 參數。例如,若使用OpenAICompatProvider 或 DashScopeProvider,可傳入 content_type、system_prompt、user_prompt、temperature等。

  • 傳回值

    DataFrame 對象,追加模型輸出內容(預設為output 列)。

  • 樣本

    文本調用

    pf.set_model_provider(pf.OpenAICompatProvider(task="chat/completions"))
    
    questions = pf.from_dict({
        "id": [1, 2],
        "question": ["What is Flink?", "What is stream processing?"],
    })
    
    # default output column: output (STRING)
    df = questions.llm.predict("question", model="qwen3.6-plus")
    
    # custom output column: answer (STRING)
    df = questions.llm.predict(
        "question",
        model="qwen3.6-plus",
        output_type=pf.DataType.struct({
            "answer": pf.DataType.string()
        }))

    多模態調用

    pf.set_model_provider(pf.OpenAICompatProvider(task="chat/completions"))
    
    tickets = pf.from_dict({
        "question": ["Is this item damaged?"],
        "image_url": ["https://example.com/images/order-1001.jpg"],
    })
    
    # multimodal input columns: one text column and one image column
    df = tickets.llm.predict(
        "question",
        "image_url",
        model="qwen3.6-plus",
        content_type=["TEXT", "IMAGE_URL"],
    )

    結果緩衝

    pf.set_model_provider(pf.OpenAICompatProvider(task="chat/completions"))
    
    df = questions.llm.predict(
        "question",
        model="qwen3.6-plus",
        cache_table="`fluss-catalog`.default_database.predict_cache",
        cache_key=["id", "question"])
    說明

    僅 Flink AI服務(內建模型)支援多模態調用和結果緩衝功能。

文本類

文本分類

  • 介面名稱:ai_classify。

    DataFrame.llm.ai_classify(
        input_col,
        labels,
        *,
        provider=None,
        model=None,
        cache_table=None,
        cache_key=None,
        config=None,
        **kwargs
    )
  • 功能描述:將文本分類到指定標籤列表中的某一個。

  • 入參

    參數名稱

    參數類型

    是否必填

    描述

    input_col

    String / Expression

    是

    輸入文本列名或列運算式。

    labels

    List[String]

    是

    分類標籤列表,如 ["positive", "negative", "neutral"]。

    其餘參數的含義參見通用調用。

    說明

    ai_classify等垂類 AI 函數會使用內建 system prompt,Model Provider 配置的 system prompt 不生效。

  • 傳回值

    DataFrame 對象,追加 category (STRING) 和 confidence (DOUBLE) 列,包含分類結果和置信分數。

  • 樣本

    pf.set_model_provider(pf.OpenAICompatProvider(task="chat/completions"))
    df = pf.from_dict({"review": ["Great product", "Terrible, do not buy", "It is okay"]})
    df = df.llm.ai_classify("review",
                            labels=["positive", "negative", "neutral"],
                            model="qwen3.6-plus")

情感分析

  • 介面名稱:ai_sentiment。

    DataFrame.llm.ai_sentiment(
        input_col,
        *,
        provider=None,
        model=None,
        cache_table=None,
        cache_key=None,
        config=None,
        **kwargs
    )
  • 功能描述:對輸入文本進行情感分析。

  • 入參

    參數名稱

    參數類型

    是否必填

    描述

    input_col

    String / Expression

    是

    輸入文本列名或列運算式。

    其餘參數的含義參見通用調用。

  • 傳回值

    DataFrame 對象,追加以下列,包含情感分析結果:

    • score (DOUBLE): 情感分析分數,在 -1.0 到 1.0 之間。

    • label (STRING): “positive”, “negative”, “neutral” 之一。

    • confidence (DOUBLE): 置信分數。

  • 樣本

    pf.set_model_provider(pf.OpenAICompatProvider(task="chat/completions"))
    df = pf.from_dict({"comment": ["This feature is amazing!", "Broke after one month"]})
    df = df.llm.ai_sentiment("comment", model="qwen3.6-plus")

資訊提取

  • 介面名稱:ai_extract。

    DataFrame.llm.ai_extract(
        input_col,
        schema,
        *,
        provider=None,
        model=None,
        cache_table=None,
        cache_key=None,
        config=None,
        **kwargs
    )
    
  • 功能描述:按照給定的 JSON Schema 從文本中提取結構化資訊。

  • 入參

    參數名稱

    參數類型

    是否必填

    描述

    input_col

    String / Expression

    是

    輸入文本列名或列運算式。

    schema

    String

    是

    JSON Schema 字串,描述要提取的欄位,如 '{"name":"STRING", "phone":"STRING"}'。

    其餘參數的含義參見通用調用。

  • 傳回值

    DataFrame 對象,追加 extracted_json (STRING) 列,包含提取的結構化資訊。

  • 樣本

    pf.set_model_provider(pf.OpenAICompatProvider(task="chat/completions"))
    df = pf.from_dict({"text": ["John Smith, male, 28 years old, phone ***-****"]})
    schema = '{"name": "STRING", "age": "INTEGER", "phone": "STRING"}'
    df = df.llm.ai_extract("text", schema=schema,
                           model="qwen3.6-plus")

文本翻譯

  • 介面名稱:ai_translate。

    DataFrame.llm.ai_translate(
        input_col,
        source_lang,
        target_lang,
        *,
        provider=None,
        model=None,
        cache_table=None,
        cache_key=None,
        config=None,
        **kwargs
    )
  • 功能描述:將文本從源語言翻譯為目標語言。

  • 入參

    參數名稱

    參數類型

    是否必填

    描述

    input_col

    String / Expression

    是

    輸入文本列名或列運算式。

    source_lang

    String

    是

    源語言代碼,如 "zh"、"en"、"auto"(自動檢測)。支援:auto、zh、en、ja、ko、fr、de、es、ru、ar、pt。

    target_lang

    String

    是

    目標語言代碼,不可為 "auto"。

    其餘參數的含義參見通用調用。

  • 傳回值

    DataFrame 對象,追加 translated_text (STRING) 和 detected_language (STRING) 列,包含翻譯結果和識別到的語言。

  • 樣本

    pf.set_model_provider(pf.OpenAICompatProvider(task="chat/completions"))
    df = pf.from_dict({"text": ["Hello World", "How are you?"]})
    df = df.llm.ai_translate("text", source_lang="en", target_lang="zh",
                             model="qwen3.6-plus")

文本摘要

  • 介面名稱:ai_summarize。

    DataFrame.llm.ai_summarize(
        input_col,
        max_length,
        *,
        provider=None,
        model=None,
        cache_table=None,
        cache_key=None,
        config=None,
        **kwargs
    )
    
  • 功能描述:將文本摘要到指定最大長度。

  • 入參

    參數名稱

    參數類型

    是否必填

    描述

    input_col

    String / Expression

    是

    輸入文本列名或列運算式。

    max_length

    int

    是

    摘要的最大字元數,必須大於 0。

    其餘參數的含義參見通用調用。

  • 傳回值

    DataFrame 對象,追加 summary (STRING) 列,包含摘要文本。

  • 樣本

    pf.set_model_provider(pf.OpenAICompatProvider(task="chat/completions"))
    df = pf.from_dict({"article": ["This is a long article with lots of content..."]})
    df = df.llm.ai_summarize("article", max_length=100,
                             model="qwen3.6-plus")
    

資料脫敏

  • 介面名稱:ai_mask。

    DataFrame.llm.ai_mask(
        input_col,
        entities,
        *,
        provider=None,
        model=None,
        cache_table=None,
        cache_key=None,
        config=None,
        **kwargs
    )
    
  • 功能描述:對文本中的敏感資訊進行脫敏處理。

  • 入參

    參數名稱

    參數類型

    是否必填

    描述

    input_col

    String / Expression

    是

    輸入文本列名或列運算式。

    entities

    List[String]

    是

    需要脫敏的實體類型列表,如 ["name", "phone"]。

    其餘參數的含義參見通用調用。

  • 傳回值

    DataFrame 對象,追加 masked_text (STRING) 和 detected_entities (ARRAY<STRING>) 列,包含脫敏後的文字和檢測到的實體。

  • 樣本

    pf.set_model_provider(pf.OpenAICompatProvider(task="chat/completions"))
    df = pf.from_dict({"text": ["Please contact John Smith at 555-0123"]})
    df = df.llm.ai_mask("text", entities=["name", "phone"],
                        model="qwen3.6-plus")

向量類

向量搜尋

說明
  • vector_search 介面從Realtime ComputeFlink版VVR引擎11.8及以上版本支援。

  • 本文所述 output_columns 結果列投影和映射別名能力從Realtime ComputeFlink版VVR引擎11.9及以上版本支援。

  • 在VVR 11.8中,output_columns 僅用於重新命名全部輸出資料行:非彙總模式必須提供與向量表全部列及 score 數量相同的名稱,彙總模式必須提供一個外層數組列名。升級到VVR 11.9及以上版本後,請按照本文所述的投影語義調整該參數。

  • 介面名稱:vector_search。

    DataFrame.llm.vector_search(
        search_source,
        column_to_search,
        column_to_query,
        top_k,
        *,
        agg=False,
        output_columns=None,
        config=None,
        ignore_empty=False
    )
  • 功能描述:使用當前 DataFrame 中的查詢向量,到向量檢索源中尋找最相似的記錄,並把檢索結果追加到當前 DataFrame。

  • 入參

    參數名稱

    參數類型

    是否必填

    描述

    search_source

    DataFrame

    是

    向量檢索源 DataFrame,例如通過 read_milvus 讀取的向量集合。

    column_to_search

    String

    是

    檢索源中的向量列名。

    column_to_query

    String / Expression

    是

    當前 DataFrame 中的查詢向量列名或列運算式。

    top_k

    int

    是

    每條輸入記錄返回的最相似結果數量。

    agg

    Boolean

    否

    是否把 Top K 結果彙總到一個數組列中。預設值為 False。

    output_columns

    List[String] / Mapping[String, String]

    否

    可選的向量搜尋結果列。列表用於選擇列並保留原列名;agg=False 時還可以使用映射,其鍵用於選擇列、值作為輸出別名。可選擇 search_source 中的頂層列以及引擎產生的 score 列。預設值為 None,表示選擇全部結果列。

    config

    Dict

    否

    運行時向量搜尋配置。

    ignore_empty

    Boolean

    否

    是否丟棄沒有檢索結果的輸入行。預設值為 False。

  • 傳回值

    DataFrame 對象,包含原始列和追加的向量檢索結果列。設 output_columns 最終選擇 M 個結果列:

    • 未指定 `output_columns` 時,預設返回 search_source 的全部列,以及一個 DOUBLE 類型的檢索分值列,預設名為 score。分值的含義和排序方向由 Connector 及其距離度量決定;使用 Milvus 時請結合 search_metric 解釋該值。

    • 當 `agg=False` 時,每個輸入行最多會對應 `top_k` 條輸出行,並追加 M 列。列表按照聲明順序選擇列並保留原名;映射按照鍵的聲明順序選擇列,並使用對應的值作為輸出別名。

    • 當 `agg=True` 時,每條有檢索結果的輸入最多產生一條輸出,並追加固定名為 search_results 的 ARRAY<ROW<...>> 列。預設 ignore_empty=False 時會保留所有輸入記錄;沒有檢索結果時 search_results 為 NULL。設定 ignore_empty=True 後,沒有檢索結果的輸入記錄不會出現在結果中。數組元素為包含 M 個所選欄位的 ROW。此模式僅支援使用列表投影內部欄位,不支援映射。可以在調用完成後使用 `rename_columns("search_results", "新列名")` 重新命名外層數組列。

    • `output_columns` 不可為空,列名和別名均不可為空或重複。所選列必須是 `search_source` 的頂層列或者產生的相似性列。返回順序與列表或映射鍵的聲明順序一致。

    • 如果 `search_source` 已存在 `score`、`score0` 等列,引擎會為產生的相似性列選擇唯一名稱,例如 `score2`;此時需要在 `output_columns` 中使用實際產生的列名。

    • 非彙總模式下,可以使用映射為結果列指定不衝突的別名。如果列表或預設輸出與當前 DataFrame 的已有列重名,請先使用 `rename_columns` 重新命名當前 DataFrame 中的衝突列,再調用 `vector_search`。彙總模式下,如果當前 DataFrame 已有 `search_results` 列,也需要先重新命名該列。

    • 如果向量檢索源使用的連接器支援列裁剪下推,引擎會嘗試將 `output_columns` 對應的列裁剪下推到連接器;無論連接器是否支援下推,最終結果都只包含所選的向量搜尋結果列。

  • VVR 11.8升級說明

    VVR 11.8中的 output_columns 表示“全部輸出資料行的別名”,VVR 11.9及以上版本中則表示“需要選擇的結果列”。例如,VVR 11.8中的以下調用:

    output_columns=["match_doc_id", "match_embedding", "match_title", "match_score"]

    升級後應改為映射形式:

    output_columns={
        "doc_id": "match_doc_id",
        "embedding": "match_embedding",
        "title": "match_title",
        "score": "match_score",
    }
  • 樣本

    from array import array
    import pyflink.dataframe as pf
    from pyflink.dataframe import DataType
    
    query_df = pf.from_dict({
        "query_id": [1],
        "query_embedding": [array("f", [0.1, 0.2, 0.3])],
    })
    
    documents = pf.read_milvus(
        endpoint="http://milvus.example.com",
        username="${secret_values.milvus_user}",
        password="${secret_values.milvus_password}",
        database_name="commerce",
        collection_name="support_docs",
        schema={
            "doc_id": DataType.int64(),
            "embedding": DataType.list(DataType.float32()),
            "title": DataType.string(),
        },
        search_metric="COSINE",
    )
    
    selected_docs = query_df.llm.vector_search(
        documents,
        column_to_search="embedding",
        column_to_query="query_embedding",
        top_k=3,
        output_columns=["doc_id", "title", "score"],
    )

    列表形式會投影結果列,並保留原列名。需要同時指定別名時,可以使用映射:

    matched_docs = query_df.llm.vector_search(
        documents,
        column_to_search="embedding",
        column_to_query="query_embedding",
        top_k=3,
        output_columns={
            "doc_id": "match_doc_id",
            "title": "match_title",
            "score": "match_score",
        },
    )

    彙總模式下,列表選擇數組元素中的欄位,外層數組列固定名為 search_results。如需重新命名外層數組列,可以調用 rename_columns:

    matched_docs_agg = query_df.llm.vector_search(
        documents,
        column_to_search="embedding",
        column_to_query="query_embedding",
        top_k=3,
        agg=True,
        output_columns=["doc_id", "title", "score"],
    ).rename_columns("search_results", "matches")

文本向量化

  • 介面名稱:ai_embed。

    DataFrame.llm.ai_embed(
        input_col,
        dimension=1024,
        *,
        provider=None,
        model=None,
        cache_table=None,
        cache_key=None,
        config=None,
        **kwargs
    )
    
  • 功能描述:為文本產生向量嵌入(Embedding)。

  • 入參

    參數名稱

    參數類型

    是否必填

    描述

    input_col

    String / Expression

    是

    輸入文本列名或列運算式。

    dimension

    int

    否

    向量維度。預設值為 1024。

    其餘參數的含義參見通用調用。

  • 傳回值

    DataFrame 對象,追加 embedding (ARRAY<FLOAT>) 列,包含產生的向量。

  • 樣本

    pf.set_model_provider("embedding", pf.OpenAICompatProvider(task="embeddings"))
    df = pf.from_dict({"text": ["stream processing with Flink", "real-time analytics"]})
    df = df.llm.ai_embed("text", dimension=1024,
                         provider="embedding", model="text-embedding-v4")

多模態運算元

DataFrame API 可以便捷地調用多模態運算元,對圖片、音頻、視頻等多模態資料進行讀取、處理和分析,詳情請參見多模態運算元,API 文檔請參見 Multimodal Expressions。

環境與配置

API

說明

set_table_environment

設定全域 TableEnvironment

get_table_environment

擷取當前 TableEnvironment

get_or_create_table_environment

擷取或自動建立 TableEnvironment

config.set(key, value)

設定 DataFrame 配置項

config.get(key)

讀取 DataFrame 配置項

修改運行參數

  • 介面名稱:DataFrameConfig.set。

    DataFrameConfig.set(
        key, value
    )
  • 功能描述:修改 DataFrame API 作業的運行參數。您可按照下方樣本的方法配置 Python 作業參數和 Table API 參數,配置的參數會應用到預設的 TableEnvironment 上,且會覆蓋作業運行參數配置中的同名參數。

  • 入參

    參數名稱

    參數類型

    是否必填

    描述

    key

    String

    是

    參數名。

    value

    String

    是

    參數值。

  • 傳回值

    DataFrameConfig 自身,支援鏈式調用。

  • 樣本

    import pyflink.dataframe as pf
    
    pf.config.set("python.fn-execution.arrow.batch.size", "256")
    pf.config.set("table.exec.async-scalar.max-concurrent-operations", "10")
    pf.config.set("table.exec.async-lookup.timeout", "1 min")
    說明

    建議您在編寫作業時,先配置參數再定義作業邏輯,以確保參數按預期生效。