fastgpt-python-sdk/docs/advanced/detail_mode.md

Detail Mode

Learn how to use FastGPT's detail mode to get comprehensive execution data for your requests.

What is Detail Mode?

When detail=True, FastGPT returns extensive execution information including:

• Module-by-module execution details
• Token usage per module
• Execution time for each node
• Knowledge base citations
• Complete message contexts
• Cost information

Enabling Detail Mode

from fastgpt_client import ChatClient

with ChatClient(api_key="fastgpt-xxxxx") as client:
    response = client.create_chat_completion(
        messages=[{"role": "user", "content": "Explain AI"}],
        detail=True,  # Enable detail mode
        stream=False
    )
    result = response.json()

Response Structure with Detail Mode

Basic Response (detail=False)

{
    "id": "chatcmpl-xxx",
    "choices": [{
        "message": {"content": "AI is..."}
    }],
    "usage": {
        "prompt_tokens": 10,
        "completion_tokens": 50,
        "total_tokens": 60
    }
}

Detailed Response (detail=True)

{
    "id": "chatcmpl-xxx",
    "choices": [{
        "message": {"content": "AI is..."}
    }],
    "usage": {
        "prompt_tokens": 10,
        "completion_tokens": 50,
        "total_tokens": 60
    },
    "responseData": [
        {
            "moduleName": "Chat Node",
            "moduleType": "chatNode",
            "tokens": 60,
            "price": 0.0012,
            "runningTime": 1.5,
            "quoteList": [
                {
                    "sourceId": "kb_123",
                    "sourceName": "AI Knowledge Base",
                    "text": "AI stands for Artificial Intelligence..."
                }
            ],
            "completeMessages": [...]
        },
        {
            "moduleName": "Dataset Search",
            "moduleType": "datasetSearchNode",
            "tokens": 20,
            "price": 0.0004,
            "runningTime": 0.5
        }
    ]
}

Parsing Detailed Responses

def parse_detail_response(response_data: dict):
    """Parse and display detailed execution data."""

    # Basic response info
    content = response_data['choices'][0]['message']['content']
    usage = response_data.get('usage', {})
    print(f"Response: {content[:100]}...")
    print(f"Total Tokens: {usage.get('total_tokens', 0)}")

    # Detailed execution data
    response_details = response_data.get('responseData', [])

    if response_details:
        print("\n=== Execution Details ===")

        for module in response_details:
            module_name = module.get('moduleName', 'Unknown')
            module_type = module.get('moduleType', 'Unknown')
            tokens = module.get('tokens', 0)
            price = module.get('price', 0)
            running_time = module.get('runningTime', 0)

            print(f"\nModule: {module_name} ({module_type})")
            print(f"  Tokens: {tokens}")
            print(f"  Price: ${price:.6f}")
            print(f"  Runtime: {running_time}s")

            # Knowledge base citations
            quote_list = module.get('quoteList', [])
            if quote_list:
                print(f"  Citations:")
                for quote in quote_list:
                    source = quote.get('sourceName', 'Unknown')
                    text = quote.get('text', '')[:100]
                    print(f"    - {source}: {text}...")


# Usage
with ChatClient(api_key="fastgpt-xxxxx") as client:
    response = client.create_chat_completion(
        messages=[{"role": "user", "content": "What is AI?"}],
        detail=True,
        stream=False
    )
    result = response.json()
    parse_detail_response(result)

Streaming with Detail Mode

import json
from fastgpt_client import ChatClient

def stream_with_detail(client, messages):
    """Stream with detail mode events."""

    response = client.create_chat_completion(
        messages=messages,
        detail=True,
        stream=True
    )

    modules = []

    for line in response.iter_lines():
        if line.startswith("event:flowNodeStatus"):
            # Node status updates
            data = json.loads(line[6:].split('data:', 1)[1])
            status = data.get('status')
            node = data.get('moduleName')
            print(f"[{status.upper()}] {node}")

        elif line.startswith("event:flowResponses"):
            # Complete module execution data
            data = json.loads(line[6:].split('data:', 1)[1])
            modules.append(data)

        elif line.startswith("data:"):
            # Standard response chunks
            data = line[5:].strip()
            if data and data != "[DONE]":
                chunk = json.loads(data)
                if "choices" in chunk and chunk["choices"]:
                    delta = chunk["choices"][0].get("delta", {})
                    content = delta.get("content", "")
                    if content:
                        print(content, end="", flush=True)

    print("\n\n=== Module Summary ===")
    for module in modules:
        print(f"{module.get('moduleName')}: {module.get('tokens')} tokens")


# Usage
with ChatClient(api_key="fastgpt-xxxxx") as client:
    stream_with_detail(
        client,
        [{"role": "user", "content": "Explain quantum computing"}]
    )

Extracting Knowledge Base Citations

def get_citations(response_data: dict) -> list[dict]:
    """Extract knowledge base citations from detailed response."""

    citations = []
    response_details = response_data.get('responseData', [])

    for module in response_details:
        quote_list = module.get('quoteList', [])
        for quote in quote_list:
            citations.append({
                'source': quote.get('sourceName', 'Unknown'),
                'source_id': quote.get('sourceId', ''),
                'text': quote.get('text', ''),
                'module': module.get('moduleName', 'Unknown')
            })

    return citations


# Usage
with ChatClient(api_key="fastgpt-xxxxx") as client:
    response = client.create_chat_completion(
        messages=[{"role": "user", "content": "What is machine learning?"}],
        detail=True,
        stream=False
    )
    result = response.json()

    citations = get_citations(result)
    print(f"Found {len(citations)} citations:")
    for i, citation in enumerate(citations, 1):
        print(f"\n{i}. {citation['source']}")
        print(f"   {citation['text'][:150]}...")

Calculating Costs

def calculate_costs(response_data: dict) -> dict:
    """Calculate total and per-module costs."""

    total_cost = 0
    total_tokens = 0
    module_costs = []

    response_details = response_data.get('responseData', [])

    for module in response_details:
        cost = module.get('price', 0)
        tokens = module.get('tokens', 0)
        module_name = module.get('moduleName', 'Unknown')

        total_cost += cost
        total_tokens += tokens

        module_costs.append({
            'module': module_name,
            'cost': cost,
            'tokens': tokens
        })

    return {
        'total_cost': total_cost,
        'total_tokens': total_tokens,
        'modules': module_costs
    }


# Usage
with ChatClient(api_key="fastgpt-xxxxx") as client:
    response = client.create_chat_completion(
        messages=[{"role": "user", "content": "Tell me about AI"}],
        detail=True,
        stream=False
    )
    result = response.json()

    costs = calculate_costs(result)
    print(f"Total Cost: ${costs['total_cost']:.6f}")
    print(f"Total Tokens: {costs['total_tokens']}")
    print("\nPer-Module Costs:")
    for module in costs['modules']:
        print(f"  {module['module']}: ${module['cost']:.6f} ({module['tokens']} tokens)")

Analyzing Execution Time

def analyze_performance(response_data: dict) -> dict:
    """Analyze module execution performance."""

    total_time = 0
    modules = []

    for module in response_data.get('responseData', []):
        runtime = module.get('runningTime', 0)
        module_name = module.get('moduleName', 'Unknown')

        total_time += runtime
        modules.append({
            'module': module_name,
            'runtime': runtime
        })

    # Sort by runtime
    modules.sort(key=lambda x: x['runtime'], reverse=True)

    return {
        'total_time': total_time,
        'modules': modules
    }


# Usage
with ChatClient(api_key="fastgpt-xxxxx") as client:
    response = client.create_chat_completion(
        messages=[{"role": "user", "content": "Analyze this data"}],
        detail=True,
        stream=False
    )
    result = response.json()

    perf = analyze_performance(result)
    print(f"Total Runtime: {perf['total_time']:.2f}s")
    print("\nModule Execution Times:")
    for module in perf['modules']:
        print(f"  {module['module']}: {module['runtime']:.2f}s")

Use Cases

1. Debugging - Identify slow or expensive modules
2. Cost Optimization - Track token usage and costs
3. Transparency - Show sources and reasoning to users
4. Analytics - Monitor application performance
5. Compliance - Track AI-generated content sources

Best Practices

1. Use selectively - Detail mode adds overhead
2. Cache results - Store detailed data for analysis
3. Monitor costs - Track token usage over time
4. Optimize workflows - Use performance data to improve

See Also

• Streaming Events - Real-time execution events
• Record Detail API - Get details for past records