Text Extraction の入力ファイルを登録するために Python SDK の document_reference.write() を実行したところ、watsonx.ai SaaS版では正常に動作するにもかかわらず、watsonx.ai Software版では FlightUnavailableError が発生しました。

調査の結果、この処理は内部的に Flight service を利用しており、Software版では Flight service がデフォルトでクラスタ内部向けに構成されているため、ローカル PC から wdp-connect-flight を解決できなかったことが原因と考えられます。

1. Flight service とは

Flight service は、Notebook などの資産（assets）が、データソースの REST API を直接呼び出すことなく、さまざまなデータソースと連携できるようにするデータ接続サービスです。

Flight service は Apache Arrow Flight ベースの通信を利用しており、watsonx.ai や IBM Software Hub におけるデータ連携機能を支えるコンポーネントの一つとなっています。

2. 今回遭遇した事象

ローカル PC 上で Python SDK を実行して Text Extraction の入力ファイルを登録しようとしたところ、以下のエラーが発生しました。

FlightUnavailableError: Flight returned unavailable error, with message: errors resolving wdp-connect-flight:443: [field:hostname lookup error:address lookup failed for wdp-connect-flight:443: Domain name not found]

エラーが発生したコードは次のとおりです。

source_filename = "sample.pdf"

document_reference.set_client(client)
document_reference.write(source_filename)

3. 原因

document_reference.write() は、ローカルファイルをストレージへアップロードする処理です。
この処理では内部的に Flight service (wdp-connect-flight) が利用されます。
SaaS版の watsonx.ai では追加設定なしで実行できましたが、Software版では以下の違いがありました。

SaaS版	Software版
IBM Cloud が管理する接続経路を利用	Flight service はクラスタ内部のみ公開
ローカル PC から利用可能	外部からは直接利用不可

そのため、ローカル PC から Software版の Flight service に接続できず、名前解決エラーが発生していました。

4. 対応方法

Software版でローカル PC 上の Python SDK から Flight service を利用する場合は、Flight service の external route を作成します。

4-1. Flight serviceへの external route を構成する

Flight serviceへの外部ルートの構成の手順にしたがって構成します。

oc project ${PROJECT_CPD_INST_OPERANDS}

export ROUTE_NAME=flight-service

oc create route passthrough ${ROUTE_NAME} \
  --service=wdp-connect-flight

作成後、以下のコマンドでホスト名を確認します。

oc get route ${ROUTE_NAME}

実行例：

NAME             HOST/PORT
flight-service   flight-service-wx.xxx.yyy.zzz

このホスト名を Flight service の接続先として利用します。

4-2. Python SDK 側に環境変数を設定する

ローカル PC 上で実行する Python SDK から Flight service に接続するため、IBM Documentationに記載されている以下の２つの環境変数を設定します。

FLIGHT_SERVICE_LOCATION

Flight service の Route の HOST を指定します。上の例の場合：

flight-service-wx.xxx.yyy.zzz

FLIGHT_SERVICE_PORT

ポート番号を指定します。

5. watsonx.ai Notebook環境での検証

同じ Notebook を watsonx.ai 上の Notebook 環境で実行したところ document_reference.write() は正常に実行できました。

これは Notebook 実行環境が Flight service と同じクラスタ内に存在し、内部 DNS によって wdp-connect-flight を解決できるためと考えられます。このことから、Flight service 自体に問題があるのではなく、ローカル PC から Flight service への接続経路に起因する問題であることを確認できました。

6. 調査を通じてわかったこと

Flight service の external route 作成ドキュメントはすぐに見つけられましたが、クライアント側でどのような設定が必要なのかを把握することはできませんでした。今回はサポートに問い合わせを行い、 FLIGHT_SERVICE_LOCATION と FLIGHT_SERVICE_PORT を案内されたことで解決の方向性が見えました。しかし、Flight service の external route に関するドキュメントから、これらの環境変数の説明へたどり着くのは難しいと感じました。

今回の調査結果はサポートにも共有しました。Flight service を外部クライアントから利用する際に必要なクライアント設定については、external route のドキュメントからたどりやすくなるよう改善が検討されているとのことです。同じ課題に直面するユーザーが減ることを期待しています。

追記（2026-07-31）

本記事執筆時点では、Flight service の external route に関するドキュメントから、クライアント側で必要となる環境変数にたどり着くことができず、サポートへ問い合わせを行いました。

その後、watsonx.ai Python SDK のドキュメントに環境変数の設定方法が追記され、FLIGHT_SERVICE_LOCATION および FLIGHT_SERVICE_PORT がサポートされる環境変数として明記されました。環境変数の設定方法は以下のページで確認できます。

今回の調査結果やフィードバックが反映されたこともあり、現在では Flight service を外部クライアントから利用する際の設定方法が以前よりわかりやすくなりました。