LangChain デバッグバンドル

概要

トレース、バージョン、再現手順を含む LangChain の問題に関する包括的なデバッグ情報を収集します。

前提条件

• LangChain がインストールされていること
• 再現可能なエラー状態
• ログと環境へのアクセス

手順

ステップ 1: 環境情報の収集

# debug_bundle.py
import sys
import platform
import subprocess

def collect_environment():
    """Collect system and package information."""
    info = {
        "python_version": sys.version,
        "platform": platform.platform(),
        "packages": {}
    }

    # Get LangChain package versions
    packages = [
        "langchain",
        "langchain-core",
        "langchain-community",
        "langchain-openai",
        "langchain-anthropic",
        "openai",
        "anthropic"
    ]

    for pkg in packages:
        try:
            result = subprocess.run(
                [sys.executable, "-m", "pip", "show", pkg],
                capture_output=True, text=True
            )
            for line in result.stdout.split("\n"):
                if line.startswith("Version:"):
                    info["packages"][pkg] = line.split(":")[1].strip()
        except:
            info["packages"][pkg] = "not installed"

    return info

print(collect_environment())

ステップ 2: 完全なトレーシングの有効化

import os
import langchain

# Enable debug mode
langchain.debug = True

# Enable LangSmith tracing (if available)
os.environ["LANGCHAIN_TRACING_V2"] = "true"
os.environ["LANGCHAIN_PROJECT"] = "debug-session"

# Custom callback for logging
from langchain_core.callbacks import BaseCallbackHandler
from datetime import datetime

class DebugCallback(BaseCallbackHandler):
    def __init__(self):
        self.logs = []

    def on_llm_start(self, serialized, prompts, **kwargs):
        self.logs.append({
            "event": "llm_start",
            "time": datetime.now().isoformat(),
            "prompts": prompts
        })

    def on_llm_end(self, response, **kwargs):
        self.logs.append({
            "event": "llm_end",
            "time": datetime.now().isoformat(),
            "response": str(response)
        })

    def on_llm_error(self, error, **kwargs):
        self.logs.append({
            "event": "llm_error",
            "time": datetime.now().isoformat(),
            "error": str(error)
        })

    def on_tool_start(self, serialized, input_str, **kwargs):
        self.logs.append({
            "event": "tool_start",
            "time": datetime.now().isoformat(),
            "tool": serialized.get("name"),
            "input": input_str
        })

    def on_tool_error(self, error, **kwargs):
        self.logs.append({
            "event": "tool_error",
            "time": datetime.now().isoformat(),
            "error": str(error)
        })

ステップ 3: 最小限の再現スクリプトの作成

# minimal_repro.py
"""
Minimal reproduction script for LangChain issue.
Run with: python minimal_repro.py
"""
import os
from langchain_openai import ChatOpenAI
from langchain_core.prompts import ChatPromptTemplate

# Setup (redact actual API key in report)
os.environ["OPENAI_API_KEY"] = "sk-..."

def reproduce_issue():
    """Reproduce the issue with minimal code."""
    try:
        llm = ChatOpenAI(model="gpt-4o-mini")
        prompt = ChatPromptTemplate.from_template("Test: {input}")
        chain = prompt | llm

        # This is where the error occurs
        result = chain.invoke({"input": "test"})
        print(f"Success: {result}")
    except Exception as e:
        print(f"Error: {type(e).__name__}: {e}")
        import traceback
        traceback.print_exc()

if __name__ == "__main__":
    reproduce_issue()

ステップ 4: デバッグバンドルの生成

import json
from datetime import datetime
from pathlib import Path

def create_debug_bundle(error_description: str, logs: list):
    """Create a complete debug bundle."""
    bundle = {
        "created_at": datetime.now().isoformat(),
        "description": error_description,
        "environment": collect_environment(),
        "trace_logs": logs,
        "steps_to_reproduce": [
            "1. Install packages: pip install langchain langchain-openai",
            "2. Set OPENAI_API_KEY environment variable",
            "3. Run: python minimal_repro.py"
        ]
    }

    # Save bundle
    output_path = Path("debug_bundle.json")
    output_path.write_text(json.dumps(bundle, indent=2))
    print(f"Debug bundle saved to: {output_path}")

    return bundle

# Usage
debug_callback = DebugCallback()
# Run your code with callback...
# llm = ChatOpenAI(callbacks=[debug_callback])

create_debug_bundle(
    error_description="Chain fails with OutputParserException",
    logs=debug_callback.logs
)

出力

• 完全な診断情報を含む debug_bundle.json
• 問題再現用の minimal_repro.py
• 環境情報とバージョン情報
• タイムスタンプ付きのトレースログ

デバッグバンドルの内容

{
  "created_at": "2025-01-06T12:00:00",
  "description": "Issue description",
  "environment": {
    "python_version": "3.11.0",
    "platform": "Linux-6.8.0",
    "packages": {
      "langchain": "0.3.0",
      "langchain-core": "0.3.0",
      "langchain-openai": "0.2.0"
    }
  },
  "trace_logs": [...],
  "steps_to_reproduce": [...]
}

提出前のチェックリスト

• すべてのファイルから API キーを削除
• 最小限の再現スクリプトが独立して動作
• エラーメッセージとスタックトレースを含める
• パッケージバージョンが記載されている
• 期待される動作と実際の動作が説明されている

リソース

• LangChain GitHub Issues
• LangSmith トレーシング
• LangChain Discord

次のステップ

langchain-common-errors を使用して迅速に修正するか、バンドルを添えてエスカレーションします。