langchain-architecture

LangChain アーキテクチャ

エージェント、チェーン、メモリ、ツール統合を活用して、高度な LLM アプリケーションを構築するための LangChain フレームワークを習得します。

このスキルを使用する場面

• ツールにアクセスできる自律型 AI エージェントを構築する
• 複雑な複数ステップの LLM ワークフローを実装する
• 会話のメモリと状態を管理する
• LLM を外部データソースや API と統合する
• モジュール式で再利用可能な LLM アプリケーションのコンポーネントを作成する
• ドキュメント処理パイプラインを実装する
• 本番環境向けの LLM アプリケーションを構築する

基本概念

1. エージェント

実行するアクションを LLM が判断する自律型システムです。

エージェントの種類：

• ReAct：推論と行動を交互に行います
• OpenAI Functions：関数呼び出し API を活用します
• Structured Chat：複数入力のツールに対応します
• Conversational：チャットインターフェース向けに最適化されています
• Self-Ask with Search：複雑なクエリを分解します

2. チェーン

LLM またはその他のユーティリティへの呼び出しを連ねたものです。

チェーンの種類：

• LLMChain：基本的なプロンプトと LLM の組み合わせです
• SequentialChain：複数のチェーンを順番に実行します
• RouterChain：入力を特化型チェーンに振り分けます
• TransformChain：ステップ間でデータを変換します
• MapReduceChain：集約を伴う並列処理を行います

3. メモリ

やり取りをまたいでコンテキストを維持するシステムです。

メモリの種類：

• ConversationBufferMemory：すべてのメッセージを保存します
• ConversationSummaryMemory：古いメッセージを要約します
• ConversationBufferWindowMemory：直近の N 件のメッセージを保持します
• EntityMemory：エンティティに関する情報を追跡します
• VectorStoreMemory：意味的類似性に基づいて情報を取得します

4. ドキュメント処理

ドキュメントを読み込み、変換し、取得できるように保存します。

コンポーネント：

• Document Loaders：さまざまなソースから読み込みます
• Text Splitters：ドキュメントを適切な単位に分割します
• Vector Stores：埋め込みを保存し、取得します
• Retrievers：関連するドキュメントを取得します
• Indexes：効率的にアクセスできるようドキュメントを整理します

5. コールバック

ログ記録、監視、デバッグのためのフックです。

用途：

• リクエストとレスポンスのログ記録
• トークン使用量の追跡
• レイテンシの監視
• エラー処理
• カスタムメトリクスの収集

クイックスタート

from langchain.agents import AgentType, initialize_agent, load_tools
from langchain.llms import OpenAI
from langchain.memory import ConversationBufferMemory

# Initialize LLM
llm = OpenAI(temperature=0)

# Load tools
tools = load_tools(["serpapi", "llm-math"], llm=llm)

# Add memory
memory = ConversationBufferMemory(memory_key="chat_history")

# Create agent
agent = initialize_agent(
    tools,
    llm,
    agent=AgentType.CONVERSATIONAL_REACT_DESCRIPTION,
    memory=memory,
    verbose=True
)

# Run agent
result = agent.run("What's the weather in SF? Then calculate 25 * 4")

アーキテクチャパターン

パターン 1：LangChain による RAG

from langchain.chains import RetrievalQA
from langchain.document_loaders import TextLoader
from langchain.text_splitter import CharacterTextSplitter
from langchain.vectorstores import Chroma
from langchain.embeddings import OpenAIEmbeddings

# Load and process documents
loader = TextLoader('documents.txt')
documents = loader.load()

text_splitter = CharacterTextSplitter(chunk_size=1000, chunk_overlap=200)
texts = text_splitter.split_documents(documents)

# Create vector store
embeddings = OpenAIEmbeddings()
vectorstore = Chroma.from_documents(texts, embeddings)

# Create retrieval chain
qa_chain = RetrievalQA.from_chain_type(
    llm=llm,
    chain_type="stuff",
    retriever=vectorstore.as_retriever(),
    return_source_documents=True
)

# Query
result = qa_chain({"query": "What is the main topic?"})

パターン 2：ツールを使うカスタムエージェント

from langchain.agents import Tool, AgentExecutor
from langchain.agents.react.base import ReActDocstoreAgent
from langchain.tools import tool

@tool
def search_database(query: str) -> str:
    """Search internal database for information."""
    # Your database search logic
    return f"Results for: {query}"

@tool
def send_email(recipient: str, content: str) -> str:
    """Send an email to specified recipient."""
    # Email sending logic
    return f"Email sent to {recipient}"

tools = [search_database, send_email]

agent = initialize_agent(
    tools,
    llm,
    agent=AgentType.ZERO_SHOT_REACT_DESCRIPTION,
    verbose=True
)

パターン 3：複数ステップのチェーン

from langchain.chains import LLMChain, SequentialChain
from langchain.prompts import PromptTemplate

# Step 1: Extract key information
extract_prompt = PromptTemplate(
    input_variables=["text"],
    template="Extract key entities from: {text}\n\nEntities:"
)
extract_chain = LLMChain(llm=llm, prompt=extract_prompt, output_key="entities")

# Step 2: Analyze entities
analyze_prompt = PromptTemplate(
    input_variables=["entities"],
    template="Analyze these entities: {entities}\n\nAnalysis:"
)
analyze_chain = LLMChain(llm=llm, prompt=analyze_prompt, output_key="analysis")

# Step 3: Generate summary
summary_prompt = PromptTemplate(
    input_variables=["entities", "analysis"],
    template="Summarize:\nEntities: {entities}\nAnalysis: {analysis}\n\nSummary:"
)
summary_chain = LLMChain(llm=llm, prompt=summary_prompt, output_key="summary")

# Combine into sequential chain
overall_chain = SequentialChain(
    chains=[extract_chain, analyze_chain, summary_chain],
    input_variables=["text"],
    output_variables=["entities", "analysis", "summary"],
    verbose=True
)

メモリ管理のベストプラクティス

適切なメモリタイプの選択

# For short conversations (< 10 messages)
from langchain.memory import ConversationBufferMemory
memory = ConversationBufferMemory()

# For long conversations (summarize old messages)
from langchain.memory import ConversationSummaryMemory
memory = ConversationSummaryMemory(llm=llm)

# For sliding window (last N messages)
from langchain.memory import ConversationBufferWindowMemory
memory = ConversationBufferWindowMemory(k=5)

# For entity tracking
from langchain.memory import ConversationEntityMemory
memory = ConversationEntityMemory(llm=llm)

# For semantic retrieval of relevant history
from langchain.memory import VectorStoreRetrieverMemory
memory = VectorStoreRetrieverMemory(retriever=retriever)

コールバックシステム

カスタムコールバックハンドラー

from langchain.callbacks.base import BaseCallbackHandler

class CustomCallbackHandler(BaseCallbackHandler):
    def on_llm_start(self, serialized, prompts, **kwargs):
        print(f"LLM started with prompts: {prompts}")

    def on_llm_end(self, response, **kwargs):
        print(f"LLM ended with response: {response}")

    def on_llm_error(self, error, **kwargs):
        print(f"LLM error: {error}")

    def on_chain_start(self, serialized, inputs, **kwargs):
        print(f"Chain started with inputs: {inputs}")

    def on_agent_action(self, action, **kwargs):
        print(f"Agent taking action: {action}")

# Use callback
agent.run("query", callbacks=[CustomCallbackHandler()])

テスト戦略

import pytest
from unittest.mock import Mock

def test_agent_tool_selection():
    # Mock LLM to return specific tool selection
    mock_llm = Mock()
    mock_llm.predict.return_value = "Action: search_database\nAction Input: test query"

    agent = initialize_agent(tools, mock_llm, agent=AgentType.ZERO_SHOT_REACT_DESCRIPTION)

    result = agent.run("test query")

    # Verify correct tool was selected
    assert "search_database" in str(mock_llm.predict.call_args)

def test_memory_persistence():
    memory = ConversationBufferMemory()

    memory.save_context({"input": "Hi"}, {"output": "Hello!"})

    assert "Hi" in memory.load_memory_variables({})['history']
    assert "Hello!" in memory.load_memory_variables({})['history']

パフォーマンスの最適化

1. キャッシュ

from langchain.cache import InMemoryCache
import langchain

langchain.llm_cache = InMemoryCache()

2. バッチ処理

# Process multiple documents in parallel
from langchain.document_loaders import DirectoryLoader
from concurrent.futures import ThreadPoolExecutor

loader = DirectoryLoader('./docs')
docs = loader.load()

def process_doc(doc):
    return text_splitter.split_documents([doc])

with ThreadPoolExecutor(max_workers=4) as executor:
    split_docs = list(executor.map(process_doc, docs))

3. ストリーミングレスポンス

from langchain.callbacks.streaming_stdout import StreamingStdOutCallbackHandler

llm = OpenAI(streaming=True, callbacks=[StreamingStdOutCallbackHandler()])

リソース

• references/agents.md：エージェントアーキテクチャの詳細
• references/memory.md：メモリシステムのパターン
• references/chains.md：チェーンの構成戦略
• references/document-processing.md：ドキュメントの読み込みとインデックス作成
• references/callbacks.md：監視と可観測性
• assets/agent-template.py：本番環境対応のエージェントテンプレート
• assets/memory-config.yaml：メモリ設定の例
• assets/chain-example.py：複雑なチェーンの例

よくある落とし穴

1. メモリのオーバーフロー：会話履歴の長さを管理していない
2. ツール選択の誤り：ツールの説明が不十分で、エージェントが混乱する
3. コンテキストウィンドウ超過：LLM のトークン上限を超える
4. エラー処理の欠如：エージェントの失敗を捕捉して処理していない
5. 非効率な検索：ベクトルストアへのクエリを最適化していない

本番環境チェックリスト

• 適切なエラー処理を実装する
• リクエストとレスポンスのログ記録を追加する
• トークン使用量とコストを監視する
• エージェントの実行にタイムアウト制限を設定する
• レート制限を実装する
• 入力検証を追加する
• エッジケースをテストする
• 可観測性を設定する（コールバック）
• フォールバック戦略を実装する
• プロンプトと設定をバージョン管理する