localGPT日志分析：结构化日志文件和错误排查指南

【免费下载链接】localGPT Chat with your documents on your local device using GPT models. No data leaves your device and 100% private. 项目地址: https://gitcode.com/GitHub_Trending/lo/localGPT

概述

localGPT作为一款本地化文档问答系统，其日志系统设计精良，提供了丰富的调试和监控信息。本文将深入解析localGPT的日志架构、常见错误模式以及专业的排查方法，帮助开发者快速定位和解决系统问题。

日志系统架构

多层级日志管理

localGPT采用分层日志架构，包含以下核心组件：

日志文件结构

日志文件	用途	日志级别	格式
logs/system.log	系统全局日志	INFO/ERROR	时间戳 + 级别 + 消息
logs/ollama.log	Ollama服务日志	INFO	时间戳 + 原始输出
logs/rag-api.log	RAG API服务日志	INFO	时间戳 + 原始输出
logs/backend.log	后端服务日志	INFO	时间戳 + 原始输出
logs/frontend.log	前端服务日志	INFO	时间戳 + 原始输出

核心日志功能解析

1. 彩色日志格式化

localGPT使用自定义的ColoredFormatter类，为不同服务和日志级别提供视觉区分：

class ColoredFormatter(logging.Formatter):
    COLORS = {
        'DEBUG': '\033[36m',     # Cyan
        'INFO': '\033[32m',      # Green
        'WARNING': '\033[33m',   # Yellow
        'ERROR': '\033[31m',     # Red
        'CRITICAL': '\033[35m',  # Magenta
    }
    
    SERVICE_COLORS = {
        'ollama': '\033[94m',    # Blue
        'rag-api': '\033[95m',   # Magenta
        'backend': '\033[96m',   # Cyan
        'frontend': '\033[93m',  # Yellow
        'system': '\033[92m',    # Green
    }

2. 查询处理日志

RAG系统提供详细的查询处理日志记录：

def log_query(query: str, sub_queries: List[str] | None = None) -> None:
    """记录用户查询和分解的子查询"""
    border = "=" * 60
    logger.info("\n%s\nUSER QUERY: %s", border, query)
    if sub_queries:
        for i, q in enumerate(sub_queries, 1):
            logger.info("  sub-%d → %s", i, q)
    logger.info("%s", border)

3. 检索结果日志

检索过程的结果记录功能：

def log_retrieval_results(results: List[Dict], k: int) -> None:
    """显示前k个检索结果的chunk_id、截断文本和分数"""
    if not results:
        logger.info("Retrieval returned 0 documents.")
        return
    
    logger.info("Top %d results:", min(k, len(results)))
    header = f"{'chunk_id':<14} {'score':<7} preview"
    logger.info(header)
    logger.info("-" * len(header))
    
    for row in results[:k]:
        preview = shorten(row.get("text", ""), width=60, placeholder="…")
        logger.info("%s %-7.3f %s", str(row.get("chunk_id"))[:12], 
                   row.get("score", 0.0), preview)

常见错误模式及排查指南

1. 服务启动失败错误

症状：❌ Failed to start [service_name] 错误信息

排查步骤：

1. 检查端口占用：lsof -i :[port] 或 netstat -tulpn | grep :[port]
2. 验证服务依赖：确保Ollama、Python、Node.js正确安装
3. 查看详细错误：检查对应服务的.log文件获取具体错误信息

常见原因：

• 端口冲突（11434, 8000, 8001, 3000）
• 依赖软件未安装或版本不兼容
• 环境变量配置错误

2. 模型加载错误

症状：⚠️ Could not check/pull models 或模型相关超时

排查方法：

# 手动检查Ollama状态
ollama list
ollama ps

# 手动拉取模型
ollama pull qwen3:8b
ollama pull qwen3:0.6b

3. 检索性能问题

症状：查询响应缓慢或检索结果质量差

诊断命令：

# 实时监控日志
tail -f logs/system.log
tail -f logs/rag-api.log

# 查看检索评分分布
grep "score" logs/rag-api.log | head -20

高级日志分析技巧

1. 日志聚合分析

使用awk和grep进行日志分析：

# 统计错误类型分布
grep "ERROR" logs/system.log | awk '{print $4}' | sort | uniq -c

# 提取特定时间段的日志
sed -n '/2025-01-01 10:00:00/,/2025-01-01 11:00:00/p' logs/system.log

# 分析服务启动时间
grep "Starting\|started" logs/system.log | grep -E "(ollama|rag-api|backend)"

2. 性能监控脚本

创建自定义监控脚本：

#!/bin/bash
# monitor_localgpt.sh

LOG_DIR="logs"
ALERT_THRESHOLD=5  # 错误次数阈值

# 监控错误频率
error_count=$(grep -c "ERROR" $LOG_DIR/system.log)
if [ $error_count -gt $ALERT_THRESHOLD ]; then
    echo "警告: 检测到 $error_count 个错误"
    grep "ERROR" $LOG_DIR/system.log | tail -5
fi

# 检查服务状态
for service in ollama rag-api backend; do
    if ! curl -s http://localhost:$(grep -A5 "$service" run_system.py | \
        grep "port" | awk -F': ' '{print $2}' | tr -d ',')/health > /dev/null; then
        echo "服务 $service 可能已宕机"
    fi
done

3. 结构化日志查询

使用jq处理JSON格式的日志（如果启用）：

# 假设日志包含JSON输出
grep "retrieval" logs/rag-api.log | jq '.score, .chunk_id'

故障排除流程图

最佳实践建议

1. 日志轮转配置

建议配置日志轮转以防止日志文件过大：

# 使用logrotate配置
sudo nano /etc/logrotate.d/localgpt

# 配置内容
/logs/*.log {
    daily
    rotate 7
    compress
    missingok
    notifempty
    copytruncate
}

2. 监控告警设置

设置关键指标监控：

监控指标	阈值	告警动作
错误日志频率	>5次/分钟	发送邮件通知
服务响应时间	>2000ms	重启服务
内存使用率	>80%	优化配置
CPU使用率	>90%	扩展资源

3. 调试模式启用

在开发环境中启用详细调试：

# 启用调试模式
python run_system.py --mode dev

# 查看详细日志
export LOG_LEVEL=DEBUG

总结

localGPT的日志系统提供了全面的监控和调试能力。通过理解其日志架构、掌握常见错误模式的分析方法，以及运用专业的排查技巧，开发者可以快速定位和解决系统问题。建议定期审查日志、设置监控告警，并建立系统化的故障处理流程，确保localGPT系统的稳定运行。

记住，良好的日志实践是系统可靠性的基石。通过本文提供的指南，您将能够充分利用localGPT的日志功能，构建更加健壮的文档问答系统。

【免费下载链接】localGPT Chat with your documents on your local device using GPT models. No data leaves your device and 100% private. 项目地址: https://gitcode.com/GitHub_Trending/lo/localGPT