TrueFoundryで初めてのLanggraphエージェントをデプロイする

このガイドでは、 LangGraph エージェントを TrueFoundryにデプロイする方法をご紹介します。TrueFoundryは、最小限のDevOpsやMLOpsの専門知識でAIデプロイメントを簡素化するために設計されたプラットフォームです。TrueFoundryはインフラ管理、スケーリング、モニタリングを自動化し、デプロイの複雑さに煩わされることなく、インサイトの導出に集中できるようにします。数回クリックするだけで、自然言語のリクエストをSQLクエリや動的なチャートに変換でき、データ探索をシームレスかつインテリジェントにします。手動でのクエリは不要です！

直接お試しになりたい場合は、TrueFoundryプラットフォームにアクセスし、「Live Demos」と「Langgraph-Streamlit」に進んでください。 エージェントワークフローのライブデモ

アーキテクチャ概要

このプロジェクトは、連携して動作するいくつかの主要コンポーネントで構成されています。

クエリ・エージェント

• 自然言語理解のためにGPT-4oを使用
• ClickHouse向けに適切なSQLクエリを生成
• 事前設定されたデータベースに対してSQLクエリを実行
• 可視化エージェントへの入力としてデータを表形式で返す

可視化エージェント：2番目のAIエージェントで、

• データに基づいて最適な可視化タイプを決定
• matplotlib/seabornを使用してプロットを生成
• 可視化の書式設定とスタイル設定を担当します

FastAPIバックエンド: RESTful APIで、

• Langgraphを使用してエージェント間の連携を調整します
• 非同期ジョブ処理を管理します
• プロット画像と結果を提供します

Streamlitフロントエンド: ユーザーインターフェースで、

• 直感的なクエリインターフェースを提供します
• リアルタイムの処理状況を表示します
• インタラクティブな可視化を表示します

‍

データフロー

1. ユーザーはStreamlit UIを通じて自然言語クエリを送信します
2. クエリはSQLエージェントによって処理され、SQLが生成されます
3. SQLはClickHouseデータベースに対して実行されます
4. 結果はプロットエージェントに渡されます
5. プロットエージェントが適切なプロットを作成します
6. 結果はStreamlit UIに表示されます

‍はじめに

リポジトリをクローンする

まず、 TrueFoundry Getting Started Examples リポジトリにアクセスし、クローンします。

git clone <https://github.com/truefoundry/getting-started-examples.git>

Plot Agent ディレクトリへ移動する

plot_agent ディレクトリに移動します。

cd getting-started-examples/plot_agent/langgraph_plot_agent

環境設定

仮想環境を作成し、アクティベートするには：

python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

依存関係をインストールする

pip install -r requirements.txt

環境設定

環境設定ファイルの例をコピーします。

```bash
cp .env.example .env
```

を作成します .env ファイルに認証情報を記述します

# Truefoundry LLMGateway Configuration if using Truefoundry LLM Gateway for calling models
LLM_GATEWAY_BASE_URL=your_llm_gateway_base_url_here
LLM_GATEWAY_API_KEY=your_llm_gateway_api_key_here

# OPENAI API Configuration if not using Truefoundry LLM Gateway
OPENAI_API_KEY=<your_openai_api_key_here>

# ClickHouse Database Configuration
CLICKHOUSE_HOST=your_clickhouse_host_here
CLICKHOUSE_PORT=443
CLICKHOUSE_USER=your_clickhouse_user_here
CLICKHOUSE_PASSWORD=your_clickhouse_password_here
CLICKHOUSE_DATABASE=default

注：TrueFoundry LLM Gateway を使用する場合、モデルIDの形式は provider-name/model-name （例： openai-main/gpt-4o）です。お使いの .env ファイルには、環境設定セクションに示されているように、正しいLLM Gatewayの認証情報が含まれています。

ClickHouseの認証情報を取得するには、 clickhouse、サインインしてサービスを作成します。サービスをクリックすると、左サイドバーの中央に接続ボタンが表示され、それをクリックすると、以下に示す認証情報が表示されます。ファイルをアップロードしてデータベースを作成するか、事前に定義されたものを使用できます。

LangGraphエージェントの実装

このプロジェクトでは2つのLangGraphエージェントを使用しており、これはまた、 AutoGen vs LangGraph マルチエージェントワークフロー設計における評価を行う際にも役立つ実用的な参考資料となります。OpenAIのみを使用したい場合は、以下を置き換えてください。

model=OpenAIChat(
        id="openai-main/gpt-4o",  # Format: provider-name/model-name
        api_key=os.getenv("LLM_GATEWAY_API_KEY"),
        base_url=os.getenv("LLM_GATEWAY_BASE_URL")
    ),

以下で:

model=OpenAIChat(
        id="gpt-4o",  # Specify model here
        api_key=os.getenv("OPENAI_API_KEY")
      ),

これらは、 Langflow vs LangGraph がオーケストレーションの選択肢としてよく挙げられるような設定で構成されています。 

class State(TypedDict):
    messages: Annotated[list[AnyMessage], add_messages]

tools_list = [execute_clickhouse_query, create_plot]

def tools_condition_modified(state):
    ans = tools_condition(state)
    human_messages_id = [m.id for m in state["messages"] if m.type == "human"]
    if ans == "tools":
        return "tools"
    else:
        return "__end__"

def create_agent():
    builder = StateGraph(State)

    llm = ChatOpenAI(
        model=os.getenv("MODEL_ID"), 
        api_key=os.getenv("LLM_GATEWAY_API_KEY"), 
        base_url=os.getenv("LLM_GATEWAY_BASE_URL"),
        streaming=True  # Enable streaming for the LLM
    )

    llm.bind_tools(tools_list)

    # Define nodes: these do the work
    builder.add_node("assistant", llm)
    builder.add_node("tools", ToolNode(tools_list))

    # Define edges: these determine how the control flow moves
    builder.add_edge(START, "assistant")
    builder.add_edge("tools", "assistant")
    builder.add_conditional_edges(
        "assistant",
        tools_condition_modified,
    )
    builder.add_edge("assistant", "__end__")

    agent = builder.compile()
    return agent

agent = create_agent()

サービスの実行

FastAPIサーバーを起動します:

python api.py

Streamlit UIを起動します（新しいターミナルで）:

streamlit run app.py

TrueFoundryへのデプロイ

前提条件

TrueFoundry CLIをインストールします:

pip install -U "truefoundry"

TrueFoundryにログインします:

tfy login --host "<https://app.truefoundry.com>"

デプロイ手順

1. TrueFoundryの「Deployments」セクションに移動します。

2. 下部にある「Service」をクリックします。
3. クラスターワークスペースを選択します。
4. ノートパソコン、GitHub、またはDockerからデプロイできます。ノートパソコンからデプロイする場合は、上記の前提条件を完了していることを確認してください。
5. TrueFoundryプラットフォームは`deploy.py`ファイルを生成し、プロジェクトに追加します。このファイルを編集して環境変数を追加する必要があります。生成されたファイル内の`env`セクションを見つけ、資格情報を追加してください。

# In the generated deploy.py file, locate the env section and add your variables:  
  env={
      # If using OPENAI  
      "OPENAI_API_KEY": "your_openai_api_key",  
      # If using LLM_GATEWAY
      "LLM_GATEWAY_API_KEY": "your_llm_gateway_api_key",
      "LLM_GATEWAY_BASE_URL": "your_llm_gateway_base_url",
      "CLICKHOUSE_HOST": "your_clickhouse_host",  
      "CLICKHOUSE_PORT": "443",  
      "CLICKHOUSE_USER": "your_user",  
      "CLICKHOUSE_PASSWORD": "your_password",  
      "CLICKHOUSE_DATABASE": "default",  
      "MODEL_ID": "gpt-4o"  
  },  

プレースホルダーの値を実際の資格情報に置き換えてください。これらの環境変数がないと、アプリケーションは正しく機能しません。

6. デプロイコマンドを実行します。

python deploy.py

SQLおよびPlot Workflow APIがTrueFoundryにデプロイされ、実行されています！

7. すべてが機能していることを確認するには、curlを使用してテストクエリを送信できます。

curl -X POST -H "Content-Type: application/json" \  
  -d '{"query": "Show me the cost trends by model over the last week"}' \  
  https://Langgraph-plot-agent-demo-8000.aws.demo.truefoundry.cloud/query  

すべてが正しく設定されていれば、次のような応答が返されます。

{  
  "job_id": "123e4567-e89b-12d3-a456-426614174000",  
  "status": "processing",  
  "message": "Query is being processed. Check status with /status/{job_id}"  
}  

監視と管理

TrueFoundryダッシュボードにアクセスして、以下を実行します。

• リソース使用状況を監視する
• アプリケーションログを表示する
• 必要に応じてリソースをスケーリングする
• オートスケーリングルールを設定する

アプリケーションのヘルスチェック：

• バックエンドのヘルスチェック：/health
• APIドキュメント：/docs
• メトリクス: /metrics

使用例:

1. API経由でクエリを送信:

curl -X POST "https://plot-agent-8000.your-workspace.truefoundry.cloud/query" \  
     -H "Content-Type: application/json" \  
     -d '{"query": "Show me the cost trends by model over the last week"}'  

2. Streamlit UI経由で:

• UIのURLにアクセスします
• テキスト入力欄にクエリを入力します
• リアルタイムのクエリ処理と結果を表示します

APIエンドポイント

クエリを送信

curl -X POST http://localhost:8000/query \  
  -H "Content-Type: application/json" \  
  -d '{"query": "Show me the cost trends by model over the last week. Filter models that show a 0 cost."}'  

‍

レスポンス

{  
  "job_id": "123e4567-e89b-12d3-a456-426614174000",  
  "status": "processing",  
  "message": "Query is being processed. Check status with /status/{job_id}"  
}  

‍

ジョブのステータスを確認

curl -X GET http://localhost:8000/status/123e4567-e89b-12d3-a456-426614174000  

‍

プロット画像を取得

curl -X GET http://localhost:8000/plot/123e4567-e89b-12d3-a456-426614174000 --output plot.png  

Streamlitを個別にデプロイする

FastAPIとStreamlit間の適切な通信を確保するため、TrueFoundryプラットフォーム上でStreamlitを別のサービスとしてデプロイする必要があります。

1. TrueFoundry上で、StreamlitフロントエンドをFastAPIとは別にデプロイします。
2. FastAPIでCORSを設定:

from fastapi.middleware.cors import CORSMiddleware  

app.add_middleware(  
    CORSMiddleware,  
    allow_origins=["*"],  
    allow_credentials=True,  
    allow_methods=["*"],  
    allow_headers=["*"],  
)  

3. Streamlitで環境変数を定義

Streamlitアプリケーションでは、FastAPIバックエンドを指す環境変数を使用する必要があります。あなたの Streamlit環境 設定:

FASTAPI_ENDPOINT="https://langgraph-plot-agent-demo-8000.aws.demo.truefoundry.cloud"

次に、あなたの Streamlitアプリ がこの環境変数を読み込むように変更します:

import os

FASTAPI_ENDPOINT = os.getenv("FASTAPI_ENDPOINT", "http://localhost:8000")

これにより、Streamlitが正しいFastAPIインスタンスを動的に参照することが保証されます。

        4. 異なるポートを使用する

ローカルでデプロイする場合、またはTrueFoundryがポートの競合を自動的に処理しない場合は、 FastAPIとStreamlitが異なるポートで実行されることを確認してください。

例:

FastAPI: https://langgraph-plot-agent-demo-8000.aws.demo.truefoundry.cloud

Streamlit: https://langgraph-streamlit-demo-8501.aws.demo.truefoundry.cloud

ローカルでStreamlitを異なるポートで実行するには:

streamlit run app.py --server.port 8501

エージェントにトレースを追加する

トレーシングは、エージェントの実行が呼び出された際に内部で何が起こっているかを理解するのに役立ちます。Truefoundryのトレーシング機能を使用し、わずかなコードを追加するだけで、エージェントの実行パス、行われたツール呼び出し、使用されたコンテキスト、かかったレイテンシーを把握できます。

以下をインストールする必要があります。

 pip install traceloop-sdk

次に、トレーシングを有効にするために必要な環境変数を追加します。

"TRACELOOP_BASE_URL": "<your_host_name>/api/otel" # "https://internal.devtest.truefoundry.tech/api/otel"
"TRACELOOP_HEADERS"="Authorization=Bearer%20<your_tfy_api_key>"

エージェントを定義しているコードベースに、これらの行を追加するだけでトレーシングを有効にできます。

from traceloop.sdk import Traceloop
Traceloop.init(app_name="langraph")

補足事項

両方のサービスをデプロイした後、必ず以下を確認してください。

• StreamlitからFastAPIへのAPI接続をテストする。
• Streamlitの .env ファイルを正しいFastAPIエンドポイントで更新する。
• CORS設定がStreamlitからのリクエストを許可していることを確認する。

これにより、SQLおよびプロットワークフローAPIが両方のサービス間で適切に機能することが保証されます。

‍

‍