メインコンテンツまでスキップ

テクニカルライターとAIエージェント：Artieの開発を通じて学んだこと

· 約15分
Pedro Vega
Pedro Vega
テクニカルライター | UXライター | コンテンツデザイナー | ニューヨーク在住

テクニカルライターの多くは、AIエージェントを開発するわけではありません。私たちはそれらをドキュメント化します。スプリントレビューに参加し、アーキテクチャの決定事項を記録した資料を読み込みます。そして、金曜日までに統合を機能させる必要がある人に、検索パイプラインをどのように説明すべきかを考えます。

しかし、私はあえて一つ作ってみました。

その名は**Artie**。Algoliaを使用して構築し、このポートフォリオサイトに組み込んだAIドキュメントアシスタントです。彼を作る過程で、私はどのカンファレンスの講演やホワイトペーパーよりも、ライティングと人工知能の交差点について多くを学びました。

これはArtieの設計に関する解説ではありません――それについては**ケーススタディ**をご覧ください。ここでは、より広範な教訓についてお話しします：

  • AIエージェントとは実際に何なのか
  • リトリバル・オーグメンテッド・ジェネレーション（RAG）の仕組み
  • プロンプトエンジニアリングが、多くの人が思っている以上にテクニカルライティングに近い理由
  • そして、これらすべてが私たちのこの小さな世界にとって何を意味するのか

AIエージェントとは何か、そうでないものは何か？​

「AIエージェント」という用語は、かなり大雑把に使われているため、定義しておく価値があります。AIを活用した機能すべてがエージェントというわけではありません。機械学習を用いたスペルチェッカーはエージェントではありません。オートコンプリートの候補表示もエージェントではありません。 厳格な決定木に従うチャットボットでさえ、実際にはエージェントとは言えません。それは、テキスト入力を備えたフローチャートに過ぎないからです。

AIエージェントとは、定義された環境内で目標を解釈し、その達成方法を推論し、行動を起こすことができるシステムのことです。重要な違いは、制約条件内での自律性にあります。 エージェントは単にプロンプトに応答するだけでなく、文脈を評価し、戦略を選択し、実行します――多くの場合、複数のステップにまたがって行われます。

では、Artieはこのスペクトラムのどこに位置するのでしょうか？

彼は特化型のエージェントです。ウェブを閲覧したり、コードを実行したり、複数のステップにわたるツール呼び出しを連鎖させたりはしません。 しかし、ユーザーの意図（「これは技術的な質問か、それともポートフォリオに関する問い合わせか？」）を解釈し、応答戦略を選択し、自律的にガードレールを適用することは行います。これは単なるチャットボット以上のものです。一方で、例えばユーザーの質問に基づいてバグ報告を提出できるような、完全に自律的なエージェントには及びません。

この区別が重要なのは、AIツールやエージェントを理解することが、テクニカルライターの仕事においてますます重要な要素となっているからです。AIを活用した製品のドキュメントを作成する際には、それがこのスペクトラムのどこに位置するかを把握する必要があります。そして、「AI」という言葉に対して異なる期待を抱いている可能性のあるユーザーに対して、その違いを明確に伝える必要があります。

リトリバル・オーグメンテッド・ジェネレーション（RAG）の実際の仕組み​

リトリバル・オーグメンテッド・ジェネレーション（RAG）は、Artieや、増え続けるAI搭載ドキュメントツールの背後にあるアーキテクチャパターンです。この概念は、大規模言語モデル（LLM）が抱える根本的な制限に対処するものです。つまり、LLMは静的なデータセットで学習されており、特定のコンテンツに関するデータを含んでいないという点です。

標準的なLLMとのやり取りは次のように行われます。ユーザーがプロンプトを送信すると、モデルは学習データに基づいて応答を生成します。これは一般的な知識については問題ありませんが、特定の分野に関する質問に対しては機能しません。ベースモデルに自社製品のAPIについて尋ねても、モデルはでたらめな回答を返すか、丁寧に回答を拒否するでしょう。

RAGは、ユーザーの質問とモデルの応答の間に「検索」というステップを挿入します。その処理の流れは以下の通りです：

  1. クエリ処理。 ユーザーの質問を受け取り、検索に適した形式に変換します。これは、クエリをベクトル埋め込み（質問の意味的意味を数値で表現したもの）に変換することで行われます。
  2. 検索。 システムはナレッジベースを検索し、クエリと意味的に類似したコンテンツを探します。 この場合、ナレッジベースはドキュメントの事前構築済みインデックスとなります。検索ではキーワードマッチングではなく、意味に基づく類似性が使用されるため、「認証の設定方法は？」と「ログイン認証情報の設定」は、同じドキュメントページと一致することになります。
  3. コンテキストの組み立て。 検索されたドキュメント（またはドキュメントの断片）は、ユーザーの元の質問やシステムのプロンプトとともに、コンテキストウィンドウに組み立てられます。この組み立てられたパッケージが、モデルによって処理される対象となります。
  4. 生成。 モデルは、一般的な学習データではなく、検索されたコンテキストに基づいて応答を生成します。システムが適切に構成されている場合、モデルは出典を明記し、検索されたドキュメントに実際に記載されている内容の範囲内にとどまります。

RAG pipeline

RAGシステムの品質は、ステップ2で決まります。検索層が誤った文書を抽出したり、優先順位付けを誤ったりすれば、モデルがどれほど高性能であっても意味がありません。 間違った情報源から、もっともらしく、構成の整った回答を生成してしまうことになるからです。だからこそ、インデックス作成戦略、チャンキング手法、そして埋め込みモデルの選択は、多くの人が予想する以上に重要になるのです。生成モデルが評価されることが多いですが、実際の重労働を担っているのは検索層なのです。

Artieの場合、ナレッジベースは当サイトに公開されているドキュメントであり、Algoliaを通じてインデックス化および検索が行われます。これは意図的な制約です。Artieは、ここに記載されていない事柄に関する質問には答えられません。 ケーススタディでは、その制約が実際にどのように機能するかを解説していますが、アーキテクチャ上の重要なポイントは次の通りです。RAGはモデルをより賢くするものではありません。 RAGは、モデルの応答を検証可能な情報源に紐付けることで、モデルをより説明責任のあるものにするのです。

プロンプトエンジニアリングとはテクニカルライティングである​

これが、プロジェクト全体を通じて得られた最大の気づきでした。システムプロンプトの作成は、その本質においてテクニカルライティングの実践なのです。

よく練られたシステムプロンプトには何が含まれるかを考えてみてください。対象読者を定義する必要があります。トーンや語り口のガイドラインを確立する必要があります。範囲の境界、つまりシステムが扱うべきこと、扱うべきでないことを設定する必要があります。エッジケースを予測し、人間の判断を必要とせずに機械が従えるほど正確な指示を書く必要があります。 また、最も重要なルールが優先されるよう、情報を階層的に整理する必要があります。

これは単なるプロンプトエンジニアリングではありません。これは、対象読者分析、スタイルガイド、コンテンツ仕様書が1つの文書にまとめられたものです。

必要なスキルの転用はほぼ1対1です：

  • 対象者分析 → 対象者へのルーティング。 テクニカルライターは対象読者を特定し、それに応じてコンテンツを調整します。システムプロンプトは、AI に対して同じことを行います。Artie のプロンプトは、テクニカルユーザーと採用担当者との間でルーティングを行いますが、これは、よく構成されたドキュメントサイトが異なる読者ペルソナの間でルーティングを行うのと同じ仕組みです。
  • スタイルガイド → ペルソナの調整。 どのドキュメントチームにも、文体やトーンに関するガイドラインがあります。システムプロンプトはAIのためのスタイルガイドです。「ここでは簡潔に」「あそこでは親しみやすく」「このフレーズは絶対に使わない」「出典リンクは常に記載する」といった指示です。
  • 情報アーキテクチャ → 指示の階層構造。 テクニカルライターは、情報の順序や構造が理解度に影響を与えることを知っています。システムプロンプトについても同様で、モデルが指示に従うかどうかは、その指示がどこに配置され、どのように構成されているかによって左右されます。
  • エッジケースのドキュメント → ガードレール設計。 優れたドキュメントは、ユーザーが予期せぬ行動をとることを想定し、明確な指針を提供します。優れたプロンプト設計もまた、ユーザーがシステムを破壊しようと試みることを想定し、明確な境界線を提示します。

すべてのテクニカルライターがプロンプトエンジニアになるべきだと言っているわけではありません。私が言いたいのは、プロンプトエンジニアリングという分野が、テクニカルライターが数十年にわたって培ってきたスキルから多大な影響を受けているということです。明確で、構造化され、対象読者を意識したドキュメントを書けるのであれば、あなたは想像以上にこの仕事に必要な資質を備えているのです。

ガードレールは言語の問題である​

AIのセキュリティについて考える際、人々はそれをエンジニアリング上の問題として捉えがちです。例えば、レート制限、認証、モデルへのアクセス制御などです。これらは確かに重要です。しかし、一般向けに公開されている対話型AIの場合、セキュリティ上のリスクの大部分は言語的なものです。

プロンプトインジェクションとは、本質的に、言語を用いて言語ベースの制御を迂回しようとする試みです。これに対抗するには、敵対的な入力がモデルを誤導できないほど曖昧さのないルールを策定する必要があります。

備考

プロンプトインジェクションとは、ユーザーが「これまでの指示をすべて無視する」といった指示を用いて、システムのプロンプトを上書きしようと試みることを指します。

Open Worldwide Application Security Project（OWASP）の大規模言語モデルアプリケーションのトップ10リスクでは、プロンプトインジェクションが最大のリスクとして挙げられています。 しかし、このリストを読み進めると、リスクの多くが根本的には言語の問題であることに気づくでしょう：

  • 出力処理の不備（モデルが出力するもの）
  • トレーニングデータの汚染（モデルがテキストから学習した内容）
  • 過剰な主体性（モデルが実行可能だと指示されたこと）

攻撃ベクトルは技術的なものですが、防御策は多くの場合、自然言語で記述され、システムのプロンプトに組み込まれています。

これにより、セキュリティに関する議論が、テクニカルライターにとって有益な形で再構築されます。私たちに認証システムの設計が求められるわけではありません。しかし、AIの振る舞いを規定する自然言語のルールを記述することに関しては、私たちは最適な立場にあります。悪意ある悪用にも耐えうる精度で、それらを記述することができるのです。

今後の方向性​

AIの未来を予測するつもりはありません。しかし、現時点で見て取れる方向性と、それがドキュメント作成を仕事とする人々にとって何を意味するのかについては説明できます。

AIを活用したドキュメントアシスタントは、単なる目新しさから「当たり前」のものへと変わりつつあります。 ユーザーは、ドキュメントサイトでの静的な検索にますます不満を抱いています。彼らは、自然言語で質問をし、10個の青いリンクではなく、根拠に基づいた具体的な回答を得たいと望んでいます。RAGベースのシステムは今やそれを可能にしており、それらを構築するためのツールもより利用しやすくなってきています。

ヒント

LLMを活用したシステムの背後にあるインフラストラクチャについて興味がありますか？ 当サイトの イベントストリームと可観測性パイプライン のドキュメントでは、Datadog や Galileo といったツールが、本番環境におけるモデル呼び出しをどのように監視・評価しているかについて解説しています。

テクニカルライターの役割は縮小しているわけではなく、むしろ拡大しています。 これらのシステムが参照するナレッジベースを管理する役割は誰かが担わなければなりません。システムの動作を制御するプロンプトを作成する役割も誰かが担わなければなりません。適用範囲の境界、文体のガイドライン、およびエラーモードを定義する役割も誰かが担わなければなりません。AIの応答が実際にドキュメントと一致しているかどうかをテストする役割も誰かが担わなければなりません。 これらはすべてライティング業務であり、人々が情報をどのように消費するかを長年考えてきた経験から得られる判断力を必要とします。

テクニカルライターは、LLM（大規模言語モデル）やRAGシステムの仕組みの基本を学ぶべきです。私たちは機械学習エンジニアになる必要はありませんが、AIを活用した製品に関する議論において、効果的な貢献者であるべきです。 パイプラインを十分に理解し、自分の専門知識がどこに適用され、どこには適用されないかを把握する必要があります。

テクニカルライターはすでに、多様な読者層に向けた文章の書き方、情報をわかりやすく構成する方法、範囲の定義、誤用の予測といったスキルを持っています。これらはAI時代において周辺的なスキルではなく、中核となるものです。

テクニカルライターはAIに取って代わられるべきではありません。テキスト生成モデルの精度は向上していますが、それでも何を、誰に、どのような制約の下で伝えるかを決定する人間が必要です。彼らには編集者が必要です。私たちこそが編集者なのです。仕事そのものは本質的に変わっていません。変わっているのはツールだけです。この仕事は消えることはありません。 いずれ、無謀な人々は自らの愚かさに気づき、優れたテクニカルライターの価値を再認識することになるでしょう。

ケーススタディを読む​

この記事で「なぜ重要なのか」と「どのように機能するのか」が理解できた方は、ケーススタディをお読みください。 ここでは、Artieの背後にある具体的な設計上の判断について解説しています：

  • 対象読者へのルーティング
  • 知識の基盤
  • ペルソナの調整
  • セキュリティ上のガードレール
  • 本番環境への展開において再考すべきトレードオフ

この2つの記事は、互いに補完し合うように設計されています。まずは、あなたの興味に合った方から読んでみてください。