Alteryxベストプラクティスシリーズの第二弾です。今回は、Alteryxの外部ドキュメンテーション化についてとなります。
Alteryxはワークフローがドキュメントになります
というのが、Alteryxの売りというか信条です。が、複雑すぎるワークフローになってくると、そんなに簡単にいきません。プログラミングでもそうですが、ある程度複雑になると各パートの理解はできたとしても、全体で見た時に何をやっているのか、というのを理解するのは徐々に困難になってきます。つまり、概要から入って、徐々にブレイクダウンしていかなければなかなか理解が追いつかないものです。
Alteryxで考えると、あまりにもツール数が増えてくると、コンテナツールに記載したタイトル文字も小さすぎて見えなくなりますし、かなり引いて見みないと（つまり、縮小するということですが）全体感がわからなくなりますし、引きすぎると個々のアイコンは小さくなりすぎてしまいます。
となると、やはり全体感を説明するような外部のドキュメントというものが欲しくなってしまいます。
外部ドキュメントを簡単に作るためには
正直なところ、ワークフローは作りっぱなしにして次々と新しいものに手を出す、というケースも多いかと思います。作っているうちは楽しいのですが、作り終えたあとのドキュメント化は正直面倒です。この面倒な作業をなるべく簡単にドキュメント化したいと思いませんか？
外部ドキュメントを簡単に作るためには、、、以前のWeekly Tipsで手法についてご紹介しました。
アドホックに何を行っているかを知りたい場合、Ask Alteryx（旧Alteryx Copilot）を使うのが良いと思います。Alteryx Oneの契約で、Designerバージョン2025.2以降であれば利用可能です。ただし、再利用性についてはあまり考えられていないようで、結果をコピーして使うことができるくらいですし（コメントツールには追加してくれます）、ワークフローの概要以外の説明もしてくれません。ただ、サマリーしてくれる内容は結構いい感じだな、と毎回思います。ポイントを抑えており、わかりやすくサマライズしてくれていると思います。
ただ、形式的な部分が欲しい、例えば、インプット、アウトプットのリストやツール統計など、決まりきったフォーマットでレポートが欲しくなるかと思います。また、過去のワークフローを一括でドキュメント化したい、といった場合もAsk Alteryxだと少し役不足です。
これらの問題を解決するために、AI（旧GenAI）ツールを使ってワークフローをドキュメント化するワークフローを作成しました。
ワークフロードキュメンテーションツール
このツールはどのようなことができるのでしょうか？Ask Alteryxの「Summarize Workflow」を使って聞いてみました。
This workflow processes Alteryx workflow files (.yxmd, .yxmc, .yxwz) to create detailed reports. It extracts metadata, categorizes tools, analyzes input/output, extracts Python code, and generates descriptions using an LLM. The final output is a comprehensive PDF report for each workflow, including an image of the canvas.
Ask Alteryxは英語で解説してくれるので、、、Google先生にお願いしてみましょう！
このワークフローは、Alteryxワークフローファイル（.yxmd、.yxmc、.yxwz）を処理して詳細なレポートを作成します。メタデータの抽出、ツールの分類、入出力の分析、Pythonコードの抽出、およびLLMを使用した説明の生成を行います。最終出力は、キャンバスの画像を含む、各ワークフローの包括的なPDFレポートです。
ちゃんと私の作成したワークフローを的確に説明してくれています。AI賢いですね。
正直な話をすると、LLMにAlteryxのワークフローをそのまま渡せば中身を解析して説明してくれます。ただし、出力を安定させるためにはプロンプトに工夫が必要です。また、そもそもワークフローのXMLを解析すれば取得することができる情報もたくさんあります。例えば、入力データや出力データはデータ入力ツールやデータ出力ツールの設定部分を抽出すれば簡単に取得できます。これを実現するために、Workflow XML Parser Toolという公式のツール（マクロ）も提供されています。決定論的にワークフローを分析するには、XMLをパースしたほうが思い通りのものができるのは確実です。一方で、ワークフローの処理内容といった人間が今まで考えないといけなかった部分はLLMにやらせることができるようになりました。
これらを総合的に考えた結果、今回のワークフローは以下のような作りとしています。
- XMLをパースすることで得られる情報はXMLを解析しています
- LLMコストの節約
- アウトプットの安定化
- ワークフローのXMLはほぼそのままXMLに渡しています
- LLMからの出力は、JSONで出力させています
- レポーティングは、Alteryxのレポーティングツールを使っています
- Markdown形式は使っていません（そもそも組織がMarkdownを許容するかどうか不明）
- LLMとXMLをパースして得られた結果を組み合わせるため（LLMはMarkdown形式で出力して来ますが、XMLをパースして得た結果をMarkdownで出力するのが面倒）
- LLMを使う際、GenAIツールを使ったバージョンと、独自のGeminiマクロを使った２つのバージョンを提供しています（オリジナルはGeminiマクロで作っていました）
なお、Geminiを呼び出す独自マクロは将来的に別途公開しようと考えています。
できること
以下の項目で構成されたレポートを作成します。
- Workflow Basic Information(ワークフロー基本情報)
- 基本情報
- 著者情報
- ワークフローメタ情報
- ワークフロー詳細設定
- Tool Statistics(ツール統計)
- ツール数、ツール種類のカウント
- カテゴリ統計
- Input/Output
- Input概要
- Ouput概要
- Workflow Canvas Image(キャンバスイメージ)
- Workflow Overview(LLMによるワークフロー解説)
- Python Code
- LLMによるワークフロー解説の出力は英語/日本語に対応しています
実際のレポートの中身
今回は、Weekly Challenge 447のソリューションファイルのサンプルレポートを元に見てみましょう。このブログではポイントを絞って見ていきたいと思います。
（ちなみに、Weekly Challenge 447は私が提出したチャレンジですので、みなさんぜひやってみてください）
まず最初にワークフローの基本情報を記載しています。ファイル名や作成したDesignerバージョン、作成者情報です。
次に、もう少し細かいワークフローの詳細な設定が並びます。
次に、ツール統計です。どのカテゴリがどれくらい使われているかをグラフィカルにみせています。
もちろんもっと細かいツールのリストも出してくれます。
さらに、データの入出力です。ここではファイルタイプや実際のファイル名などを知ることができます。
※出力部分のスクショは省略します
次にキャンバスのイメージです。やはりキャンバス上にどのようにツールが配置されているかは知りたいところです。これはPythonでプログラミングしていますが、ツールのx、y情報と接続情報を元に作成しています。
少し拡大してみましょう。
こんな感じで、ツール番号も入っていますし、Annotationも再現しています。
ちなみに、コメントツールは再現していません。
次に、LLMが出力したワークフローの説明パートです。最初にワークフロー全体の概要、そして改めて入力データ、出力データについてまとめています。
次に、レポートの内容を少し飛ばしていますが、入出力についてまとめたあとは、処理パートごとにある程度の処理の塊を分けて解説を行ってくれています。
ちなみに、このワークフローでは、このワークフローで行われることについて、
- データ準備と整形
- タスク1: アンケート完了時間の分析
- タスク2: Jupyter Notebook利用頻度の分析
- タスク3: Jupyter Notebookを表す言葉の分析
とパートをわけて解説してくれました。ちなみに、レポートを出力し直すと若干違った感じで出力されたりするのでご注意ください。
なお、上のレポートのスクリーンショットは二番目のセクションのものです。驚くほど正確に説明してくれているかと思います。
使用上の注意
一般のLLMサービスを使うため、以下のことに注意する必要があります。基本的に、LLMの準備はワークフローの利用者になるため、契約条件（送信データが再学習されるかどうか、データの処理場所など）についてはよく確認してください。
- LLMにワークフローの本体を送信するため、yxmd/yxmc/yxwzファイル内に含まれている情報はLLMに送信されることに注意してください。
- 中身のデータは送信されませんが、テキスト入力ツール内のデータやメタデータ（項目名など）は送信される可能性があります。また、計算式なども送信されます。
- LLMとしては、AIツールもしくは専用のGemini呼び出しマクロを使用して利用します。
- いずれかのLLMの契約が必要ということになります。
- 主にGoogle Gemini(2.5 flash)で開発を行っています。その他のLLMやモデルを使用すると予期しない動作が発生する可能性があります。
他にも注意点がありますが、詳細はGitHubのプロジェクトページをご覧ください。日本語のドキュメントのページも用意しています。
まとめ
AlteryxのワークフローのドキュメントをLLMを使って作成するワークフローについてご紹介しました。
Weekly Tips 110でもいくつかドキュメントツールをご紹介しましたが、基本出力が英語となってしまいます。やはり日本語のアウトプットが欲しい、ということで今回のようなツールを自作しています。
一時配布先はGitHubとしています。詳細な説明はこちら。将来的にはCommunityのGalleryでも配布しようと考えています。
なお、いくつか実現したいこともありますが、一旦は現状での提供となります。要望やご意見があれば連絡ください（Alteryx Communityでスレッド建てていただくか、DMでお願いします）。以下は改善の余地があると思っていますが、実現していない内容です。
- LLMのコスト対策は一部のみ行っています。
- Tool Statistics
- 各ツールの詳細設定は抽出していません。
- Workflow Canvas Image
- コメントツールのコメントは表示していません。
- マクロアイコンは表示していません
- Code抽出
- Rツールのコードは抽出していません。
LLMの利用は便利なので積極的に使っていきましょう！
コメント