add documents
This commit is contained in:
Xin Wang
343
docs/advanced/detail_mode.md
Normal file
343
docs/advanced/detail_mode.md
Normal file
@@ -0,0 +1,343 @@
|
||||
# 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
|
||||
|
||||
```python
|
||||
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)
|
||||
|
||||
```json
|
||||
{
|
||||
"id": "chatcmpl-xxx",
|
||||
"choices": [{
|
||||
"message": {"content": "AI is..."}
|
||||
}],
|
||||
"usage": {
|
||||
"prompt_tokens": 10,
|
||||
"completion_tokens": 50,
|
||||
"total_tokens": 60
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Detailed Response (detail=True)
|
||||
|
||||
```json
|
||||
{
|
||||
"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
|
||||
|
||||
```python
|
||||
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
|
||||
|
||||
```python
|
||||
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
|
||||
|
||||
```python
|
||||
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
|
||||
|
||||
```python
|
||||
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
|
||||
|
||||
```python
|
||||
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](streaming_events.md) - Real-time execution events
|
||||
- [Record Detail API](../api/chat_client.md#get_record_detail) - Get details for past records
|
||||
Reference in New Issue
Block a user