Rust式プラグインによるPolarsの拡張
Extending Polars with Rust Expression Plugins (fenic.ai)
要約
fenicは、AIおよびLLMパイプラインを構築するためのセマンティックDataFrameライブラリであり、そのローカルエンジンとしてPolarsを使用しています。本記事では、Polarsにネイティブで存在しないテキスト処理などの操作を、Python UDFではなくRustの式プラグインとして実装することで、パフォーマンスとコンポジションの向上を実現した方法について解説しています。これにより、これらの操作はPolarsのネイティブ式として扱われ、エンジン内で効率的に実行されます。
全文翻訳
fenicでRust式表現プラグインを用いてPolarsを拡張した理由と方法
fenicはセマンティックなDataFrameライブラリです。散らかった非構造化データ上でAIおよびLLMパイプラインを構築するためのPySparkスタイルのAPIを提供します。そのローカルエンジンはPolarsです。
この記事では、fenicを構築中に直面した特定の問題と、それを解決したPolarsの機能である式プラグインシステムについて説明します。最終的に、Polarsの式エンジンを拡張する9つのRustプラグインを作成しました。以下に、そのアプローチに至った理由と、実際のコードを用いた構築方法を解説します。
要約。 テキストに対するAIパイプラインが必要とする操作(チャンキング、プロンプトテンプレート、jq、ファジーマッチング、Markdownおよびトランスクリプト解析、よりリッチな型キャスト)はPolarsには標準で搭載されていません。これらをPython UDFとして実行すると遅く、合成性が損なわれます。pyo3-polars を介してRustでPolars式プラグインとしてこれらを記述すると、ネイティブな式になります。これらはArrow上でインエンジンで実行され、宣言された型を保持し、単一の式ツリー内で組み込みオペレーションと合成できます。UDFとプラグインのどちらを選択するか迷っているなら、プラグインを選択すべきケースです。
なぜこれを構築したのか
fenicとは
fenicは、PySparkに似たAPIを持つ、AIおよびLLMパイプライン構築のためのDataFrameライブラリです。Polarsに慣れている方にとって重要なのは、Polarsがfenicのコア実行エンジンであるということです。
記述するすべてのDataFrame操作は、Polars式、または pl.DataFrame 上のプランになります。セマンティック演算子、LLMのマップ/抽出/分類、埋め込み、類似性結合などは、すべて同じメカニズムの上に成り立っています。したがって、実際にはfenicができることは、Polarsで表現できることによって制限されます。
これは意図的な選択です。Polarsは、高速なカラムナ型、Arrowネイティブなエンジン、実際の式言語、そして遅延評価のオプティマイザーを提供します。私たちはそのどれも再構築するつもりはありませんでした。私たちはそれに付け加えたいと考えていました。
やりたかったこと
fenicがターゲットとするワークロードは、非構造化テキストに対するパイプラインです。ドキュメント、チャットログ、トランスクリプト、スクレイピングされたJSON、Markdownなどです。具体的には、Polarsがネイティブで同等の機能を持たない行レベルの操作が必要です。
- チャンク:ドキュメントを、埋め込みや検索のためにトークン数でサイズ指定された重複ウィンドウに分割します。
- プロンプトテンプレートのレンダリング:行ごとに実際のJinjaテンプレートをレンダリングします。変数は列の構造体として扱い、LLM呼び出しの前に実行します。
- JSON列のjqによるクエリ、およびMarkdownの構造化ASTへの解析。
- 文字列のファジーマッチング(6つの編集距離メトリック)による重複排除と結合。
- トランスクリプト(SRT/WebVTT)の解析:型付けされたタイムスタンプ付きキューレコードに変換します。
- 値のキャスト:fenicのよりリッチな論理型(埋め込み、Markdown、型付き構造体)にキャストします。これらはPolarsの物理データ型では直接モデル化されていません。
これらの各操作は、列全体で実行され、型付けされた結果を生成し、より大きなDataFrameパイプラインの途中にスロットインする必要があります。脇に置かれるのではなく。
明らかなアプローチが失敗した場所
Polarsにカスタム操作を追加する最も一般的な方法は、Python UDFです。行ごとの作業には map_elements、Series全体には map_batches を使用します。真に不透明でI/Oバウンドな作業(LLM API呼び出しなど)には、依然として適切なツールであり、fenicはまさにそのために map_batches を使用しています。しかし、上記のテキスト操作においては、UDFは3つの点でコストが高すぎました。
速度。 map_elements は行ごとにPythonを実行し、GILの下で、各値に対してPythonオブジェクトの往復処理が発生します。数百万行のトークン化やファジーマッチングでは、これがボトルネックになります。作業自体ではなく。
合成性。 これが実際に問題となりました。Polarsが高速なのは、式ツリー全体を計画・実行するためです。あるステップが不透明なPythonコールバックになった瞬間、エンジンはその内部を見ることができなくなります。最適化の障壁となり、マテリアライゼーションを強制し、単一パスのパイプラインを破壊します。3つのUDFをチェーンすると、エンジンとの間で3回の往復が発生します。
型。 UDFの出力型は、緩やかにアサートして期待するものです。私たちは、List<String>、Struct、固定サイズの埋め込み配列のような、実際の宣言済みデータ型を生成する操作が必要でした。これにより、残りのプランがそれらに対して型チェックできるようになります。
代替案はさらに悪かったです。Polarsをフォークしてネイティブカーネルを追加することは、フォークを永遠に所有することを意味します。DataFrameの外でテキスト作業を行い、前処理してからロードすることは、Polarsを使用する理由そのものである遅延評価と合成性を捨て去ることになります。私たちはこれらの操作を式エンジンのファーストクラスの市民にしたかったのです。それの隣ではなく。
プラグインを使う理由
Polarsには、まさにこのための専用の答えがあります:式プラグインです。Rustでカーネルを記述し、登録すると、それは通常の pl.Expr になります。エンジンにとっては、組み込みのものと区別がつきません。これは、UDFルートで欠けていたすべてのボックスにチェックを入れます。
それはインエンジンで、Rustで、Arrowバッファ上で実行されます。ベクトル化され、並列化可能で、ストリーミングの対象となり、Pythonや行ごとのオブジェクトの往復処理はありません。pl.Expr を返すため、合成可能です。プラグインは互いに、またネイティブオペレーションと、エンジンが全体として計画する単一の式ツリー内でチェーンできます。出力データ型を宣言するため、プランはカスタムステップを通じて型付けされたままになります。そしてRustは、それらを再実装することなく、ホットループ(jaq、minijinja、rapidfuzz、tiktoken、Markdownパーサー)のための成熟したエコシステムを提供してくれます。
私たちが定めたルールは、「すべてをRustで書き直す」ではありません。ネイティブPolarsは依然として高速なパスです。プラグインは、Polarsが表現できないギャップを埋めるだけです:トークナイザー、jqエンジン、キャプチャグループインデックス自体が列である正規表現。ファジーマッチングでさえ、6つのプリミティブカーネルのみをRustに保持し、通常のPolars式から高階比率を合成します。
pyo3-polars は、FFI、Arrowマーシャリング、およびキーワード引数ブリッジを生成するため、1つを記述するコストは低いです。私たちは9つ書きました。
それがもたらしたもの
最終的な状態は、述べる価値があります。fenicのテキスト操作のすべてが、ネイティブなPolars式になりました。それらは共有Arrowメモリ上でエンジン内で実行され、型を保持し、そして最も重要な部分です。それらは、Pythonの往復処理なしで、単一の式でネイティブPolarsオペレーションと合成されます。
Markdownドキュメントを解析し、そのASTをjqでフィルタリングし、結果をインデックス化し、型付き構造体にキャストすることは、単一の式です。Polarsはそれを単一パスで計画・実行し、カスタムRustと組み込みリストオペレーションを並べて実行します。ピースが揃ったら、この正確な例に戻ります。
この記事の残りの部分は、Pythonの登録からArrowメモリまで、実際のコードのみを使用して、どのように構築されるかです。
構築方法:実装ウォークスルー
メンタルモデル:契約を囲む2つの薄いレイヤー
Polars式プラグインは、2つの小さなコード片と、それらの間の明確に定義された契約です。
- Python側。 関数を登録して、ネイティブPolarsのように見せる:
expr.my_namespace.my_op(...)。 - Rust側。
&[Series]を受け取り、PolarsResult<Series>を返し、出力データ型を宣言する関数。
その間のすべては、pyo3-polars によって生成されます。FFI、Arrowマーシャリング、キーワード引数のマーシャリング、シンボルルックアップの配線。FFIには手で触れることはありません。
以下は、fenicの json.jq オペレーションの完全なPythonサーフェスです。
# src/fenic/_backends/local/polars_plugins/json.py
from pathlib import Path
import polars as pl
from polars.plugins import register_plugin_function
PLUGIN_PATH = Path(__file__).parents[3]
@pl.api.register_expr_namespace("json")
class Json:
"""Namespace for JSON-related operations on Polars expressions."""
def __init__(self, expr: pl.Expr) -> None:
self.expr = expr
def jq(self, query: str) -> pl.Expr:
return register_plugin_function(
plugin_path=PLUGIN_PATH,
function_name="jq_expr",
args=self.expr,
kwargs={"query": query},
is_elementwise=True,
)
2つのPolars APIが作業を行っています。
@pl.api.register_expr_namespace("json")は、すべてのpl.Exprに.jsonアクセサをアタッチします。インポート後、pl.col("payload").json.jq(".name")は、Polars式が合法な場所ならどこでも合法な式になります。register_plugin_function(...)は、通常のpl.Exprを返します。エンジンがそれを評価すると、plugin_pathにあるコンパイル済みライブラリをdlopenし、function_nameという名前のシンボルを探し、入力Seriesを渡し、結果を読み取ります。
これが全体のアイデアです。.json はPolarsのどこにも特別扱いされていません。ユーザー登録された名前空間であり、fenicは9つ(json、jinja、markdown、chunking、tokenization、fuzz、regexp、dtypes、transcript)を登録しています。プラグインは、式エンジンにとっては、組み込みのものと区別がつかないため、組み込みのように見えます。
(プラグインは初めてですか? Polarsプラグインドキュメント と pyo3-polars リポジトリが正規の参照資料です。)
プラグインをエンドツーエンドでウォークスルー
上記のPythonの jq メソッドは、jq_expr というRustシンボルを指しています。境界線の反対側にある、その完全なコードはこちらです。
// rust/src/json/mod.rs
use polars::prelude::*;
use polars_arrow::array::ValueSize;
use pyo3_polars::derive::polars_expr;
use serde::Deserialize;
use serde_json::Value;
#[derive(Deserialize)]
struct JqKwargs {
query: String,
}
fn jq_output(_: &[Field]) -> PolarsResult<Field> {
Ok(Field::new(
"jq".into(),
DataType::List(Box::new(DataType::String)),
))
}
#[polars_expr(output_type_func=jq_output)]
fn jq_expr(inputs: &[Series], kwargs: JqKwargs) -> PolarsResult<Series> {
// jqフィルターを一度だけコンパイルし、すべての行で再利用します。
let filter = jq::build_jq_query(&kwargs.query)
.map_err(|e| PolarsError::ComputeError(e.to_string().into()))?;
let jq_inputs = RcIter::new(core::iter::empty());
let ca = inputs[0].str()?;
let mut builder =
ListStringChunkedBuilder::new("jq".into(), ca.len(), ca.get_values_size() * 5);
for opt_str in ca.into_iter() {
if let Some(s) = opt_str {
match serde_json::from_str::<Value>(s) {
Ok(val) => {
let v: Val = val.into();
let results = filter
.run((Ctx::new([], &jq_inputs), v))
.collect::<Result<Vec<_>, _>>();
match results {
// jqの結果セットが空の場合 -> null
Ok(values) if values.is_empty() => builder.append_null(),
Ok(values) => {
let strs: Vec<String> = values.iter().map(|v| v.to_string()).collect();
builder.append_values_iter(strs.iter().map(|s| s.as_str()));
}
// クエリの失敗はバッチ全体を中止します — 行をnullにするわけではありません
Err(e) => return Err(PolarsError::ComputeError(
format!("jq query execution failed: {{e}}. Query: '{}'", kwargs.query).into(),
)),
}
}
// JSONのフォーマットが不正なのは到達不能です:列はJsonTypeで型付けされているため、
// 上流の検証により、nullでない各行は有効なJSONであることが保証されます。
Err(e) => unreachable!("Invalid JSON: {{s}} ({{e}})"),
}
} else {
builder.append_null();
}
}
Ok(builder.finish().into_series())
}
契約を理解するために必要なすべてがそのスニペットに含まれています。
- シグネチャ。
#[polars_expr(...)]属性マクロ(pyo3_polars::deriveから)は、通常のRust関数をPolarsがdlopenして呼び出すことができるエクスポートされたC-ABIシンボルに変換します。関数はinputs: &[Series]を受け取り、PolarsResult<Series>を返します。unsafeや手動のポインタ操作はありません。マクロがArrowマーシャリングを生成します。 - 型付けされた入力。
inputs[0].str()?は、最初のSeriesをStringChunkedにダウンキャストします。列が文字列でない場合、セグメンテーション違反ではなく、クリーンなPolarsErrorが返されます。 - 一度だけ作業し、行ごとではない。 jqフィルターは一度だけコンパイルされ(
build_jq_query)、すべての行で再利用されます。これは繰り返されるパターンです。コンパイル、割り当てサイジング、セットアップを行ループの外にホイストします。 - ビルダーで出力を構築する。
ListStringChunkedBuilderは、容量推定値で事前にサイズ設定され、出力列を生成します。nullセマンティクスは意図的です。append_null()は、null入力行または空のjq結果に対して発火します。jqクエリの失敗はComputeErrorでバッチを中止します。そして、JSONのフォーマットが不正な場合はunreachable!()にヒットします。なぜなら、入力列はJsonTypeで型付けされており、上流の検証によりnullでない各行は有効なJSONであることが保証されているからです。(その保証は、型付けされたエンジン上に構築することの nice な副作用です。カーネルは入力を想定できます。) Seriesを返す。builder.finish().into_series()。
jaq クレート(純粋なRustのjq)が実際のフィルタリングを行います。Polarsはカラムナの配管を提供します。プラグインはそれらの間の接合部です。
出力型、そしてなぜそれが重要なのか
属性をもう一度見てください:#[polars_expr(output_type_func=jq_output)]。その jq_output 関数は DataType::List(String) を返し、データには一切触れません。これはプラグインに関して正しく行うべき最も重要なことであり、最も間違いやすいことです。
Polarsは実行前に式スキーマを解決します。プラグインは不透明なRustです。エンジンはループを見ても何が出てくるかを推測できません。したがって、出力データ型を事前に宣言する必要があり、その宣言はデータなしで実行されなければなりません。fenicは、マクロがサポートする3つの宣言スタイルすべてを使用しており、出力型の依存度によって選択されます。
1. 静的。型は決して変わりません。 6つのファジーマッチングカーネルは常に Float64 を返します。
// rust/src/fuzz/mod.rs
#[polars_expr(output_type=Float64)]
fn normalized_indel_similarity(inputs: &[Series]) -> PolarsResult<Series> { /* ... */ }
tokenization.count_tokens も同様に固定の #[polars_expr(output_type=UInt32)] です。
2. 入力フィールドから。型は入力の関数です。 jq とテキストチャンキングはどちらも常に List<String> を生成し、入力 Field を受け取る(そしてここでは無視する)小さな関数によって宣言されます。
3. 引数から。型はキーワード引数に依存します。 ここが興味深いところです。fenicの dtypes.cast カーネルは、fenic独自の論理型システムへのキャストを実装しているため、その出力データ型は文字通り引数であり、シリアライズされたJSON型記述子として渡されます。出力型関数は、そのJSONをデシリアライズして、プラン時にPolarsデータ型を計算します。
// rust/src/dtypes/mod.rs
#[derive(Deserialize, Debug)]
pub struct CastKwargs {
source_dtype: String, // JSONエンコードされたfenic型
dest_dtype: String, // JSONエンコードされたfenic型
}
// スキーマ推論中にのみ実行されます — データには一切触れません。
fn fenic_dtype_str_to_polars_dtype(
_input_fields: &[Field],
kwargs: CastKwargs,
) -> PolarsResult<Field> {
let fenic_type = serde_json::from_str::<FenicDType>(&kwargs.dest_dtype)
.expect("Invalid Fenic type string");
Ok(Field::new("casted".into(), fenic_type.canonical_polars_type()))
}
#[polars_expr(output_type_func_with_kwargs=fenic_dtype_str_to_polars_dtype)]
fn cast_expr(inputs: &[Series], kwargs: CastKwargs) -> PolarsResult<Series> {
let src_type = serde_json::from_str::<FenicDType>(&kwargs.source_dtype)
.expect("Invalid Fenic type string");
let dest_type = serde_json::from_str::<FenicDType>(&kwargs.dest_dtype)
.expect("Invalid Fenic type string");
cast_series_to_fenic_dtype(&inputs[0], &src_type, &dest_type)
}
教訓:output_type_func_with_kwargs は、プラグインの結果型をその設定から計算できるようにし、スキーマ解決時にデコードします。これにより、完全に外部の型システム(固定サイズの埋め込み配列を含むfenicの論理型)をPolarsの物理データ型にボルトで固定し、遅延スキーマ解決を維持することが可能になります。あなたのプラグインは、事前に、データなしで、生成する形状を正確に宣言します。(正直な注意点として、これを模範として掲げているので。実際のコードは、不正な型記述子に対して .expect() するため、不正なJSON文字列はクリーンな PolarsError を表面化するのではなく、スキーマ解決パスをパニックさせます。これを堅牢化するには ComputeError にマッピングする必要があります。)
これを間違え、List<String> を宣言してから Float64 を構築した場合、コンパイルエラーにはなりません。生成された列が約束されたスキーマと一致しない場合、実行時エラーが発生します。宣言は、あなたが責任を負う契約です。
並列処理とブロードキャストを正しく行う
すべてのfenicプラグインは is_elementwise=True を渡します。そのフラグはエンジンへの約束です:この関数は各行を独立に扱います。出力の行 i は、入力の行 i のみに依存します。順序、ウィンドウ、クロス行状態はありません。
その約束は価値があります。関数がPolarsのストリーミングエンジンで実行される対象となり、オプティマイザーがそれを推論できるようになります:述語、射影、スライスプッシュダウン、さらに group_by の高速パス(関数がグループごとに1回ではなく、フラット化されたシリーズ上で実行される)。これも負荷を担っています。行をまたぐロジックを持つ関数で is_elementwise=True を設定した場合、Polarsは部分的なバッチ(ストリーミングの断片)を渡したり、group_by 内でフラット化されたグループ上で実行したりする可能性があります。どちらもクロス行ロジックを静かに破壊します。フラグはヒントではありません。それはあなたが主張する不変条件です。
「要素ごとの」処理でもブロードキャストに対処する必要があります。一般的なケースは、1つの引数がスカラーリテラル(長さ1)で、もう1つが完全な列である場合です。fenicは、カーネルに応じてこれに2つの方法で対処します。
ファジーマッチング関数は、2つの文字列列を受け取るため、ブロードキャストとnull処理を処理してくれるPolarsヘルパーに依存しています。
// rust/src/fuzz/mod.rs
#[polars_expr(output_type=Float64)]
fn normalized_indel_similarity(inputs: &[Series]) -> PolarsResult<Series> {
// 文字列操作には broadcast_binary_elementwise を使用します。nullを安全に処理するためです。
// binary_elementwise_values は null 位置でゴミデータを処理する可能性があります...
let left = inputs[0].str()?;
let right = inputs[1].str()?;
let similarity: Float64Chunked = arity::broadcast_binary_elementwise(
left,
right,
|left: Option<&str>, right: Option<&str>| match (left, right) {
(Some(left), Some(right)) => {
Some(indel::normalized_similarity(left.chars(), right.chars()) * 100.0)
}
_ => None,
},
);
Ok(similarity.into_series())
}
ここで盗むべき価値のあることが2つあります。第一に、polars::chunked_array::ops::arity の broadcast_binary_elementwise は、長さ1のブロードキャストを処理し、Option<&str> をスレッドスルーしてnullを明示します。クロージャはnullが何を意味するかを決定します(ここでは、nullを入力、nullを出力)。第二に、コードコメントに注意してください。nullチェックをスキップする *_values バリアントは意図的に避けました。なぜなら、UTF-8文字列操作では、カーネルがnullスロットのバイトに触れることを望まないからです。これは、一度噛まれてからでないとできない決定です。
正規表現カーネルは、呼び出しごとにコンパイルキャッシュが必要なため、手動で処理します。
// rust/src/regex/mod.rs
#[polars_expr(output_type=Int32)]
fn regexp_instr(inputs: &[Series]) -> PolarsResult<Series> {
let text_series = inputs[0].str()?;
let pattern_series = inputs[1].str()?;
let idx_series = inputs[2].i64()?;
let len = text_series.len();
let mut regex_cache: HashMap<String, Regex> = HashMap::new();
// 長さ1のシリーズはリテラルであり、すべての行にブロードキャストされるべきです。
let pattern_is_literal = pattern_series.len() == 1;
let idx_is_literal = idx_series.len() == 1;
// ... 行ごとのループはリテラルの場合はインデックス0、それ以外の場合はiを読み取ります ...
}
ブロードキャストは1行のコードです(if pattern_is_literal { 0 } else { i })。HashMap<String, Regex> コンパイルキャッシュは、リテラルパターンが一度コンパイルされ、後続の各行は Entry API を介してキャッシュヒットになることを意味します。
fn get_or_compile_regex<'a>(
regex_cache: &'a mut HashMap<String, Regex>,
pattern: &str,
) -> PolarsResult<&'a Regex> {
match regex_cache.entry(pattern.to_string()) {
Entry::Occupied(entry) => Ok(entry.into_mut()),
Entry::Vacant(entry) => {
let regex = Regex::new(pattern).map_err(/* ComputeError */)?;
Ok(entry.insert(regex))
}
}
}
このキャッシュは1つのチャンクに対する1回の呼び出しの間存続するため、行ごとに変動するパターン列でさえ、各ユニークなパターンは一度だけコンパイルされます。
Arrow境界、そしてゼロコピー
fenicの2つのプラグイン、JinjaレンダラーとMarkdown/JSONパスは、任意のArrow値を(文字列、整数、構造体、リスト、ネストされた組み合わせ)を外部表現に変換する必要があります。テンプレートレンダリングのための minijinja::Value、またはJSON出力のための serde_json::Value です。これは、単純なプラグインが Series イテレータを探す、あるいはさらに悪いことにPythonオブジェクトをマテリアライズするポイントです。fenicはArrow配列を直接読み取ります。これは、不要な割り当てを必要とした以前の AnyValue ベースのパスの意図的な書き直しです。Arrowバッファの読み取りはゼロコピーです。唯一の割り当ては、コンバーターが実際に構築する必要のある出力値です。
すべては1つのトレイトと1つのジェネリック関数にぶら下がっています。トレイトは「Arrowスカラーから型 V の値をどのように構築するか」を抽象化します。
// rust/src/arrow_scalar_extractor.rs
trait ArrowToValue: Sized {
fn from_null() -> Self;
fn from_str(s: &str) -> Self;
fn from_bool(b: bool) -> Self;
fn from_i64(i: i64) -> Self;
fn from_f64(f: f64) -> Self;
// ... すべてのプリミティブ幅 ...
fn from_struct(fields: Vec<(String, Self)>) -> Self;
fn from_list(values: Vec<Self>) -> Self;
}
これは minijinja::Value と serde_json::Value に対して一度ずつ実装されます。その後、単一のジェネリックコンバーターが任意のArrow配列をウォークし、どちらかを生成します。2つの公開メソッドは、具体的な型をピン留めするだけです。
pub struct ArrowScalarConverter;
impl ArrowScalarConverter {
pub fn to_jinja(&self, array: &dyn Array, row_idx: usize) -> PolarsResult<JinjaValue> {
self.convert(array, row_idx)
}
pub fn to_json(&self, array: &dyn Array, row_idx: usize) -> PolarsResult<JsonValue> {
self.convert(array, row_idx)
}
fn convert<V: ArrowToValue>(&self, array: &dyn Array, row_idx: usize) -> PolarsResult<V> {
if array.is_null(row_idx) {
return Ok(V::from_null());
}
match array.dtype() {
ArrowDataType::Utf8 => {
let a = downcast_array!(array, Utf8Array<i32>);
Ok(V::from_str(a.value(row_idx)))
}
ArrowDataType::LargeUtf8 => {
let a = downcast_array!(array, Utf8Array<i64>);
Ok(V::from_str(a.value(row_idx)))
}
ArrowDataType::Utf8View => {
let a = downcast_array!(array, Utf8ViewArray);
Ok(V::from_str(a.value(row_idx)))
}
// Binary, BinaryView, Boolean, Int8..Int64, UInt8..UInt64, Float32/64 ...
ArrowDataType::Struct(_) => self.convert_struct(downcast_array!(array, StructArray), row_idx),
ArrowDataType::List(_) => self.convert_list(downcast_array!(array, ListArray<i32>), row_idx),
ArrowDataType::LargeList(_) => self.convert_large_list(/* ListArray<i64> */),
ArrowDataType::FixedSizeList(_, _) => self.convert_fixed_size_list(/* ... */),
_ => Err(PolarsError::ComputeError(/* unsupported */)),
}
}
}
いくつか抜き出すべき点があります。
Seriesではなくpolars_arrowの&dyn Arrayで動作します。 Arrow配列(Utf8ViewArray、StructArray、ListArray<i32>など)にダウンキャストし、row_idxの値をインプレースで読み取ります。値ごとのAnyValueへのボクシングやPythonオブジェクトはありません。Utf8ViewはUtf8およびLargeUtf8と共に明示的に処理されます。 これは人々を悩ませる詳細です。最新のPolarsはデフォルトで文字列をUtf8Viewとして表現します。しかし、外部Arrow(pyarrow、一部のIPC/Parquetパス)からゼロコピーでインポートされたデータは、依然としてUtf8またはLargeUtf8として到着する可能性があります。これは、コンバーターが3つすべてに一致する正確な理由です。1つのレイアウトのみを処理するプラグインはフォールスルーして、完全に普通の文字列列でエラーになります。Arrow配列を直接読み取る場合、Polarsが提示する可能性のあるすべての物理レイアウトを知っている必要があります。- ネストは再帰です。
convert_structは各フィールドに対してconvertを呼び出します。convert_listは各要素に対してconvertを呼び出します。List<Struct<...>>は再帰から自然に生まれます。1つの関数が任意のネストされたArrowを処理します。 - 1つの実装、2つの出力。 3つ目のターゲット(例えばMessagePack値)を追加することは、さらに1つの
impl ArrowToValueです。トラバーサルは変わりません。
これは、文字列で動作するプラグインと、Arrowメモリをファーストクラスの入力として扱うプラグインの違いです。
スカラーを超えて:List<Struct> を返す
プラグインはスカラー列に限定されません。fenicのトランスクリプトパーサーは、行ごとに生のSRT/WebVTTテキストを受け取り、型付けされたキューレコードのリストを発行します。これは、入力形式に関係なく、固定の統一スキーマを持つ List<Struct> 列です。その出力型関数は、単一キューの形状を Struct として宣言します(そして、その際にフォーマット名を検証します)。
// rust/src/transcript/mod.rs
fn convert_format_to_struct(_: &[Field], kwargs: TranscriptFormatKwargs) -> PolarsResult<Field> {
// ... kwargs.format をパーサーレジストリに対して検証 ...
Ok(Field::new(
"output".into(),
DataType::Struct(vec![
Field::new("index".into(), DataType::Int64),
Field::new("speaker".into(), DataType::String),
Field::new("start_time".into(), DataType::Float64),
Field::new("end_time".into(), DataType::Float64),
Field::new("duration".into(), DataType::Float64),
Field::new("content".into(), DataType::String),
Field::new("format".into(), DataType::String),
]),
))
}
そして、行は AnyValue を使用して組み立てられ、各構造体が明示的に構築され、リストに収集されます。
let values = vec![
entry.index.map_or(AnyValue::Null, AnyValue::Int64),
entry.speaker.as_ref().map_or(AnyValue::Null, |s| AnyValue::StringOwned(s.clone().into())),
AnyValue::Float64(entry.start_time),
// end_time, duration, content, format ...
];
struct_values.push(AnyValue::StructOwned(Box::new((values, fields))));
// ...
Ok(Some(AnyValue::List(Series::new("".into(), struct_values))))
カーネルは各キューを AnyValue::StructOwned として構築し、そのフィールドは出力型関数からのキュー スキーマに揃えられ、1行のキューを AnyValue::List に収集します。したがって、列は List<Struct> として出力されます。1行での解析失敗は、バッチ全体のエラーではなく、その行の null になります。構造化された出力と正直なnullセマンティクスにより、後続の .unnest() または .explode() が結果を他のネイティブなネストされた列のように扱えるようになります。
境界を越えた設定
キーワード引数のブリッジは単なるserdeです。Python側では、プレーンな辞書を構築します(列挙型を文字列値にマーシャリングします)。
# src/fenic/_backends/local/polars_plugins/chunking.py
chunk_kwargs = {
"desired_chunk_size": desired_chunk_size,
"chunk_overlap": chunk_overlap,
"chunk_length_function_name": chunk_length_function_name.value, # enum -> str
"chunking_character_set_name": chunking_character_set_name.value,
"chunking_character_set_custom_characters": chunking_character_set_custom_characters,
}
return register_plugin_function(
plugin_path=PLUGIN_PATH, function_name="text_chunk_expr",
args=expr, kwargs=chunk_kwargs, is_elementwise=True,
)
Rust側では、一致するフィールド名を持つ #[derive(Deserialize)] 構造体を宣言し、それが入力されて関数に渡されます。
// rust/src/chunking/mod.rs
#[derive(Deserialize)]
pub struct TextChunkKwargs {
desired_chunk_size: usize,
chunk_overlap: usize,
chunk_length_function_name: String,
chunking_character_set_name: String,
chunking_character_set_custom_characters: Option<Vec<String>>,
}
Polarsはkwargs辞書をシリアライズし、deriveマクロは関数が実行される前にそれをあなたの構造体にserde経由でデシリアライズします。要求される唯一の規律は、両側が名前と形状に合意することです。スキーマによる強制はないため、Python辞書とRust構造体は手動で維持する契約です。Option<T> フィールドはPythonの None にきれいにマッピングされます。
ビルドと出荷
すべては単一のRustクレートで、単一の動的ライブラリにコンパイルされ、maturin によってビルドされます。関連する Cargo.toml:
[lib]
name = "polars_plugins"
crate-type = ["cdylib", "rlib"]
[dependencies]
polars = { version = "0.51.0", features = ["dtype-struct", "dtype-array", "timezones"] }
polars-arrow = "0.51.0"
pyo3 = { version = "0.25", features = ["abi3-py39"] }
pyo3-polars = { version = "0.24.0", features = ["derive", "dtype-struct"] }
serde = { version = "1.0.219", features = ["derive"] }
# jaq-core / jaq-json, minijinja, rapidfuzz, regex, tiktoken-rs, markdown ...
cdylib はロード可能なライブラリを生成します。rlib はRust統合テストやベンチマークから使用可能に保ちます。derive フィーチャー付きの pyo3-polars は #[polars_expr] マクロを提供します。バージョン間の連携に注意してください。pyo3-polars は正確な polars、polars-arrow、pyo3 のバージョンをピン留めし、あなたのプラグインはそれにABI互換性のあるArrow型にリンクする必要があります。そのため、スタック全体が一体となって移動する必要があります。
Pythonパッケージング側では、maturin はビルドされたモジュールを fenic パッケージ内に配置するように指示されます。
# pyproject.toml
[tool.maturin]
python-source = "src"
module-name = "fenic._polars_plugins"
これにより、コンパイルされた成果物が fenic/_polars_plugins.abi3.so に配置されます。これが、すべてのプラグインファイルが PLUGIN_PATH = Path(__file__).parents[3] を計算する理由です。.../fenic/_backends/local/polars_plugins/json.py から、3つ親を上がると .../fenic、つまり .so を保持するパッケージディレクトリになります。register_plugin_function(plugin_path=...) はそこにポインタを指し、Polarsは名前でライブラリを見つけます。
そして、そのRustスタックがロックステップでピン留めされているため、Pythonの依存関係も厳密にピン留めされています:polars>=1.34.0,<1.36.0。これはプラグイン作者の税金です。polars を単独で更新すると、依存関係グラフにPolarsクレートの互換性のない2つのコピーができ、ビルドはすべての #[polars_expr] 関数で型不一致のエラーで失敗します。クレートは意図的に一緒に移動します。新しいPolarsへのジャンプは、ロックファイル編集だけでなく、実際のコード変更を伴うことさえあります。
fenicにとってのメリット
以前、報酬は合成性だと言いました。ピースが揃った今、それがここにあります。
すべてが合成可能。 すべてのプラグインがプレーンな pl.Expr を返すため、プラグインは互いに、またネイティブPolars操作と単一の式で合成できます。これは、fenicによる「Markdownドキュメントからコードブロックを抽出する」の実装です。4つの操作のうち、3つはカスタムRustプラグイン、1つは組み込みオペレーションです。
# src/fenic/_backends/local/transpiler/expr_converter.py
return (
self._convert_expr(logical.expr)
.markdown.to_json() # Rustプラグイン: markdown -> JSON AST
.json.jq(logical.jq_query) # Rustプラグイン: ASTに対するjqフィルター
.list.get(0) # ネイティブPolarsリストオペレーション、インターリーブ
.dtypes.cast(source_dtype, dest_dtype) # Rustプラグイン: 構造体型へのキャスト
)
.json.jq(...) と .dtypes.cast(...) の間に挟まれた .list.get(0) は、まさにそのポイントです。エンジンにとって、プラグインとネイティブオペレーションの間に境界はありません。それは単一の式ツリーであり、一度計画され、データ上で単一パスで実行され、完全にPolars内で実行されます。中間Pythonリストなし、ステップごとの Series からPythonへの、そしてPythonから Series へのマーシャリングなし、エンジンを離れて戻ってくることもなし。
ネイティブ式がプラグインにフィードバックする方向でも機能します。fenicは、列をネイティブな pl.struct にパックし、それをJinjaプラグインに渡すことでLLMプロンプトを構築します。
struct_expr = pl.struct(column_exprs) # ネイティブ
return struct_expr.jinja.render(template=..., strict=...) # プラグインが行ごとにレンダリング
プラグインは構造体列を受け取り、前述の ArrowScalarConverter がRust側でその構造体のフィールドをJinja変数として読み取ることを可能にします。ネイティブオペレーションが構造体を生成し、プラグインがそれを消費し、単一の式です。カスタムカーネルが pl.Expr になると、すべてのネイティブ文字列、リスト、構造体、時間、算術オペレーションを含むPolars式言語全体が、それらの間に配置できる接着剤になります。
1つのビルド、2つのサーフェス。 Rustでロジックを記述することの、より静かなメリット。スライスをプレーンなPython関数としても公開できます。式としてだけでなく。fenicは、クエリが構築されるプラン時に、データが流れる前に、実行するのと同じRustを使用して、Jinjaフィルタと正規表現パターンを検証します。
// rust/src/lib.rs
#[pymodule]
fn _polars_plugins(_py: Python<'_>, m: &Bound<'_, PyModule>) -> PyResult<()> {
m.add_function(wrap_pyfunction!(json::py_validate_jq_query, m)?)
m.add_function(wrap_pyfunction!(regex::py_validate_regex, m)?)
Ok(())
}
py_validate_jq_query は、jq_expr カーネルが使用するのと同じ build_jq_query を呼び出し、不正なフィルターに対してPythonの ValueError を発生させます。したがって、無効なクエリは、ユーザーがそれを書いた瞬間にキャッチされ、後で実行されるのと同じパーサーで、実行中にクラッシュするのではなく。このパターンは正規表現から始まりました。Pythonの re は、PolarsのRust regex エンジン下で実行時に失敗するパターンを受け入れていましたが、同じエンジンで検証することでその乖離は終わりました。Rustクレートは、プラグインライブラリと通常の pyo3 拡張モジュールの両方です。1つのビルドから両方のサーフェスを取得できます。
これらを合計すると、プラグインシステムはfenicがAI指向の操作セット全体(トークン化、テンプレート化、解析、マッチング、キャスト)をPolarsの「横」ではなく「中」に配置することを可能にしたものです。セマンティックレイヤーはその上に座ります。高速で型付けされ、合成可能な基盤はPolarsであり、ラップされるのではなく拡張されています。
プラグイン作成者への教訓
9つのプラグインを構築して得られた教訓:
- 出力型宣言はハード契約であり、コンパイル時にはチェックされません。 構築するものを正確に宣言してください。
output_type_func_with_kwargsは、型が設定に依存する場合の脱出ハッチであり、dtypes.castが行うように、完全に外部の型システムを移植するのに十分です。 - 論理データ型だけでなく、すべての物理Arrowレイアウトに一致させてください。
Utf8およびLargeUtf8と同様にUtf8Viewも、そうしないと完全に普通の文字列列でエラーになります。そして、Python kwargs辞書とRustDeserialize構造体をロックステップで維持してください。serdeはブリッジ全体であり、それを強制するのはあなただけです。 is_elementwise=Trueは、あなたが主張する不変条件であり、ヒントではありません。 そして、静かに破ることができるものです。作業中に、セットアップ(コンパイル、割り当て、ビルダーのサイジング)を行ループの外にホイストしてください。- マクロシムとロジックを分割してください。
#[polars_expr]関数を小さく保ち、プレーンな関数(例:Jinjaのrender(...))に委譲してください。これらはcargo testで単体テスト可能で、Pythonランタイムは不要です。 - 同じRustをプレーンなpy関数としてもエクスポートして、プラン時の検証に使用してください。クエリをチェックするコードが、それを実行するコードになります。
いつプラグインに手を伸ばすべきか、そして次にどこを見るべきか
プラグインは、Polarsがネイティブで提供していない行レベルの作業が必要で、それをエンジン内で実行したい(並列、ストリーミング可能、合成可能)、そして出力を宣言済みデータ型として表現できる場合に適切なツールです。これは多くのことをカバーします。解析、トークン化、テンプレート化、ファジーマッチング、フォーマット変換、カスタムキャスト。作業が真に要素ごとでない場合、または不透明なI/Oバウンドな呼び出し(モデルAPIへのヒットなど)である場合、正直な答えは依然として map_batches または map_elements、つまりPythonのエスケープハッチであり、そこでスキーマを明示的に保つことです。
しかし、Polarsがネイティブで何かをできず、それをエンジン内に入れて合成可能にしたいというケースでは、9つのプラグインを経て、システムは持ちこたえます。Polarsに何かをボルトで固定するような感じではありません。Polarsを拡張しているような感じです。
すべての9つをコンテキストで見たい場合は、fenicはオープンソースです。Rustカーネルは rust/src/ にあり、Python名前空間は src/fenic/_backends/local/polars_plugins/ にあります。自分で書く場合は、Polarsプラグインドキュメント と pyo3-polars が開始点です。そして、その進捗をぜひお聞きしたいです。
そして、この記事があなたの時間を費やす価値があったなら、GitHubでfenicにスターを付ける ことを検討してください。これは、Polars上に構築している他の人々がそれを見つけるのを助ける最も簡単な方法であり、これらの深いダイブが書く価値があることを私たちに伝えます。