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 |
|
屬性 |
|
|
投影 / 列操作 |
|
|
過濾 |
|
|
彙總 |
|
|
串連 / 合并 |
|
|
行映射 |
|
|
展開 |
|
|
去重 |
|
|
集合運算 |
|
|
限制 / 分頁 |
|
|
分區 |
|
|
管道 |
|
|
空值處理 |
|
|
輸出 / 收集 |
|
|
調試 / 執行計畫 |
|
|
SQL |
運算式輔助函數
|
函數 |
說明 |
|
建立列參考資料表達式 |
|
|
建立字面量運算式 |
資料類型
DataType 用於描述 DataFrame 列的類型。
|
類型分類 |
方法 |
|
布爾 |
|
|
整數 |
|
|
浮點 / 定點 |
|
|
字串 |
|
|
二進位 |
|
|
日期 / 時間 |
DataType.date、DataType.time、DataType.timestamp、DataType.timestamp_ltz |
|
複合類型 |
|
|
特殊類型 |
|
|
多模態類型 |
|
|
可空性修飾 |
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 檔案 |
|
|
JSON 檔案 |
|
|
Kafka |
|
|
MaxCompute (ODPS) |
|
|
Paimon |
|
|
SLS (Log Service) |
|
|
Hologres |
|
|
Milvus |
|
|
視訊框架 |
|
|
通用 / 自訂連接器 |
資料輸出
|
資料目標 |
API |
|
Parquet 檔案 |
|
|
JSON 檔案 |
|
|
Kafka |
|
|
MaxCompute (ODPS) |
|
|
Paimon |
|
|
SLS (Log Service) |
|
|
Hologres |
|
|
Milvus |
|
|
|
自 VVR 11.9.preview.1 起支援。 |
|
通用 / 自訂連接器 |
當需要在同一個作業中進行多次資料輸出時,可以使用 create_statement_set 建立 StatementSet,統一執行多個輸出函數。
使用 Catalog
DataFrame API 可以使用 Catalog,並從 Catalog 表讀寫資料。
|
API |
說明 |
|
建立 Catalog |
|
|
擷取登入的 Catalog 對象 |
|
|
切換當前 Catalog |
|
|
擷取當前 Catalog |
|
|
列舉 Catalog |
|
|
切換當前 Database |
|
|
擷取當前 Database |
|
|
列舉當前 Catalog 下的 Database |
|
|
讀取 Catalog 表為 DataFrame |
|
|
將 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 |
說明 |
|
註冊一個模型 Provider |
|
|
設定預設 Provider(多 Provider 情境下使用) |
|
|
列舉登入的 Provider |
支援的 Provider 類型:
|
Provider |
適用情境 |
|
OpenAI、DeepSeek、靈積(百鍊)等所有 OpenAI 相容介面 |
|
|
阿里雲靈積(DashScope),支援多模態 Embedding |
|
|
NVIDIA Triton Inference Server |
|
|
用於使用登入的自訂 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 類型字串或非 StructDataType追加名為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 |
說明 |
|
設定全域 TableEnvironment |
|
|
擷取當前 TableEnvironment |
|
|
擷取或自動建立 TableEnvironment |
|
|
設定 DataFrame 配置項 |
|
|
讀取 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")說明建議您在編寫作業時,先配置參數再定義作業邏輯,以確保參數按預期生效。