Pipecatインテグレーション
Pipecatインテグレーション
Speech Engineの背後にあるLLMブレインとしてPipecatパイプラインを使用します。
このガイドでは、Speech Engineのブレインサーバー内でLLMパイプラインとしてPipecatを使用する方法を紹介します。Speech Engineは音声認識、ターンテイキング、テキスト読み上げといった音声ループを処理し、Pipecatはプロセッサーを組み合わせたパイプライン(LLM呼び出し、RAG、関数呼び出し、ガードレール、コンテンツフィルター)によってテキスト生成を処理します。
Pipecatはサーバー側のPythonフレームワークであるため、このガイドはPythonのみを対象としています。
パイプラインプロセッサーに対応するNode版はありません。pipecat-client-jsパッケージはありますが、
Pipecatサーバーと通信するブラウザクライアントであり、TypeScriptでパイプラインを構築するためのものではありません。
アーキテクチャ
Speech Engine SDKは外側のレイヤーとして実行され、ユーザーが話し終えるたびにon_transcriptコールバックが発火します。コールバック内でPipecatパイプラインを構築し、会話履歴をLLMContextFrameとして入力して、パイプラインのテキスト出力をSpeech Engineにストリーミングで返します。ElevenLabsがテキストを音声に変換し、ユーザーに再生します。
Pipecatパイプラインは1ターンの間だけ実行されます。新しいトランスクリプトが届くと、次のパイプラインを実行する前に前のパイプラインがキャンセルされます。これにより、Speech Engineの割り込み処理がパイプラインにも反映されます。
このパターンを使う場面
Pipecatは、ブレインに単一のLLM呼び出し以上の機能が必要な場合に役立ちます。
- 検索拡張生成、関数呼び出し、ガードレール向けの組み合わせ可能なプロセッサー
- 各ステップでトラフィックを検査、変換、ブロックできるフレームベースのミドルウェア
- 複数のエージェントで共有できる再利用可能なパイプラインフラグメント
ブレインが「トランスクリプトを受け取り、LLMを呼び出す」だけなら、Speech Engineクイックスタートの方が簡単です。パイプラインそのものが重要な場合はPipecatを使ってください。
前提条件
- Speech Engine。Speech Engineクイックスタートに従って作成してください。
- Python 3.10+(
pipecat-aiで必須)。 - ブレインサーバー用のパブリックHTTPSトンネル(例:ngrok)。
依存関係をインストールする
pipecat-ai[openai]にはOpenAI LLMサービスが含まれます。必要に応じて、extraを別のプロバイダー(anthropic、googleなど)に置き換えてください。
Pipecatブレインを構築する
ブレインは2つの部分で構成されます。ストリーミングされたテキストをasyncio.Queueに取り込むTextSinkプロセッサーと、1ターンのパイプラインを構築して非同期イテレーターとしてチャンクを生成するrun_pipecat_brainコルーチンです。
パイプラインにはLLMサービスとシンクのみが含まれ、Speech Engineが処理するため、STTまたはTTSプロセッサーは含まれません。入力はLLMContextFrameで、出力はLLMTextFrameチャンクです。
run_pipecat_brainは非同期ジェネレーターです。生成された各チャンクは直接Speech Engineに渡されるため、完全な応答が準備できる前にエージェントが話し始めます。
Speech Engineサーバーに接続する
Speech Engine SDKのsend_responseは文字列または文字列の任意の非同期イテラブルを受け取るため、run_pipecat_brain(transcript)を直接渡せます。Speech Engineが提供するConversationMessageオブジェクトは、ブレインに渡す前に通常のdictへ変換してください。
新しいトランスクリプトが届くと、Speech Engine SDKは前のターンのタスクをキャンセルします。これにより、run_pipecat_brain内のtry/finallyブロックを通じて、非同期ジェネレーターと基盤となるPipelineTaskがキャンセルされます。
サーバーを実行する
クイックスタートで紹介している同じトークンエンドポイントとクライアントコードを使って、ブラウザからSpeech Engineに接続します。Pipecatパイプラインはサーバー側で実行され、ブラウザからは通常のSpeech Engine会話として見えます。
パイプラインを拡張する
テキスト専用のPipecatパイプラインには、LLMTextFrameまたはLLMContextFrameを処理する任意のフレームプロセッサーを追加できます。一般的な追加例は次のとおりです。
- ガードレール:LLMの前に配置する
FrameProcessor。LLMContextFrameを検査し、安全でないコンテキストを置換またはブロックします。 - 関数呼び出し:
OpenAILLMServiceにツールを登録すると、Pipecatがツール呼び出しフレームをネイティブに処理します。最終的なアシスタントテキストは引き続きLLMTextFrameとして届きます。 - マルチステージ推論:2つの
OpenAILLMServiceインスタンスを連結し、その間に2回目の処理用コンテキストを書き換えるカスタムプロセッサーを配置します。 - 出力フィルタリング:LLMの後に配置する
FrameProcessor。各LLMTextFrameを検査し、許可されていないコンテンツをTextSinkに到達する前に削除または書き換えます。
パイプラインの形状はPipeline([processor_a, llm, processor_b, sink])のままで、run_pipecat_brainを変更する必要はありません。
本番環境での考慮事項
- キャンセルの安全性:パイプラインが完全に開始される前に
PipelineTask.cancel()を呼び出すと、デッドロックする場合があります(pipecat-ai/pipecat#4276)。上記のtry/finallyパターンは、少なくとも1つのフレームがキューに入った後にのみcancel()が実行されるため、安全です。 - プロンプトインジェクション:音声認識の出力はユーザー入力です。特に下流のプロセッサーがツール呼び出しやデータベースクエリでテキストを使用する場合は、LLMに渡す前にトランスクリプトを検証または正規化してください。
- ブレインサーバー認証:Speech Engineに共有シークレットを設定し、ブレインサーバー側で確認することで、
/wsエンドポイントへの不正な接続を防止できます。 - LLMプロバイダー:
pipecat-ai[openai]にはOpenAILLMServiceが含まれます。Anthropicの場合はpipecat-ai[anthropic]をインストールしてAnthropicLLMServiceを使用します。パイプラインの残りの部分は変わりません。