citu_vanna/docs/日志服务使用清单.md

项目日志服务使用清单

概述

本文档详细列出了项目中各个模块应该使用的日志服务，作为日志改造的实施指南。项目日志系统分为4个独立模块：app、agent、vanna、data_pipeline。

日志文件分配方案

1. agent.log - Agent相关模块

agent目录

文件	当前日志方式	目标Logger	说明
agent/citu_agent.py	print	get_agent_logger("CituAgent")	主Agent类，包含大量调试信息
agent/classifier.py	print	get_agent_logger("Classifier")	问题分类器
agent/config.py	print	get_agent_logger("Config")	配置管理
agent/state.py	无	无需日志	仅定义数据结构

agent/tools目录

文件	当前日志方式	目标Logger	说明
agent/tools/general_chat.py	print	get_agent_logger("GeneralChat")	聊天工具
agent/tools/sql_execution.py	print	get_agent_logger("SQLExecution")	SQL执行工具
agent/tools/sql_generation.py	print	get_agent_logger("SQLGeneration")	SQL生成工具
agent/tools/summary_generation.py	print	get_agent_logger("SummaryGeneration")	摘要生成工具
agent/tools/utils.py	无	get_agent_logger("ToolUtils")	工具函数（如需日志）

2. data_pipeline.log - Data Pipeline相关模块

data_pipeline根目录

文件	当前日志方式	目标Logger	说明
data_pipeline/schema_workflow.py	logging.getLogger("schema_tools.SchemaWorkflowOrchestrator")	get_data_pipeline_logger("SchemaWorkflow")	工作流编排器
data_pipeline/metadata_only_generator.py	print	get_data_pipeline_logger("MetadataGenerator")	元数据生成器
data_pipeline/config.py	无	无需日志	配置文件

data_pipeline/ddl_generation目录

文件	当前日志方式	目标Logger	说明
data_pipeline/ddl_generation/training_data_agent.py	logging.getLogger("schema_tools.Agent")	get_data_pipeline_logger("TrainingDataAgent")	训练数据代理
data_pipeline/ddl_generation/ddl_md_generator.py	无具体日志	get_data_pipeline_logger("DDLMDGenerator")	DDL/MD生成器

data_pipeline/qa_generation目录

文件	当前日志方式	目标Logger	说明
data_pipeline/qa_generation/qs_agent.py	logging.getLogger("schema_tools.QSAgent")	get_data_pipeline_logger("QSAgent")	Question-SQL代理
data_pipeline/qa_generation/qs_generator.py	无具体日志	get_data_pipeline_logger("QSGenerator")	Question-SQL生成器

data_pipeline/analyzers目录

文件	当前日志方式	目标Logger	说明
data_pipeline/analyzers/md_analyzer.py	logging.getLogger("schema_tools.MDFileAnalyzer")	get_data_pipeline_logger("MDAnalyzer")	MD文件分析器
data_pipeline/analyzers/theme_extractor.py	logging.getLogger("schema_tools.ThemeExtractor")	get_data_pipeline_logger("ThemeExtractor")	主题提取器

data_pipeline/validators目录

文件	当前日志方式	目标Logger	说明
data_pipeline/validators/sql_validator.py	logging.getLogger("schema_tools.SQLValidator")	get_data_pipeline_logger("SQLValidator")	SQL验证器
data_pipeline/validators/sql_validation_agent.py	logging.getLogger("schema_tools.SQLValidationAgent")	get_data_pipeline_logger("SQLValidationAgent")	SQL验证代理
data_pipeline/validators/file_count_validator.py	logging.getLogger("schema_tools.FileCountValidator")	get_data_pipeline_logger("FileCountValidator")	文件计数验证器
data_pipeline/validators/sql_validate_cli.py	print	get_data_pipeline_logger("SQLValidateCLI")	SQL验证命令行工具
data_pipeline/validators/sql_validation_example.py	print	get_data_pipeline_logger("SQLValidationExample")	SQL验证示例

data_pipeline/trainer目录

文件	当前日志方式	目标Logger	说明
data_pipeline/trainer/vanna_trainer.py	print	get_data_pipeline_logger("VannaTrainer")	Vanna训练器
data_pipeline/trainer/run_training.py	依赖其他模块日志	get_data_pipeline_logger("RunTraining")	训练运行脚本

data_pipeline/utils目录

文件	当前日志方式	目标Logger	说明
data_pipeline/utils/logger.py	自定义日志系统	直接删除或改造为空函数	原日志工具，直接使用新系统
data_pipeline/utils/table_parser.py	logging.getLogger("schema_tools.TableListParser")	get_data_pipeline_logger("TableParser")	表解析器
data_pipeline/utils/system_filter.py	logging.getLogger("schema_tools.SystemTableFilter")	get_data_pipeline_logger("SystemFilter")	系统表过滤器
data_pipeline/utils/permission_checker.py	logging.getLogger("schema_tools.DatabasePermissionChecker")	get_data_pipeline_logger("PermissionChecker")	权限检查器
data_pipeline/utils/large_table_handler.py	logging.getLogger("schema_tools.LargeTableHandler")	get_data_pipeline_logger("LargeTableHandler")	大表处理器
data_pipeline/utils/file_manager.py	logging.getLogger("schema_tools.FileNameManager")	get_data_pipeline_logger("FileManager")	文件管理器

data_pipeline/tools目录

文件	当前日志方式	目标Logger	说明
data_pipeline/tools/base.py	logging.getLogger + logging.debug	get_data_pipeline_logger("ToolBase")	工具基类
data_pipeline/tools/comment_generator.py	依赖base.py	get_data_pipeline_logger("CommentGenerator")	注释生成器
data_pipeline/tools/data_sampler.py	依赖base.py	get_data_pipeline_logger("DataSampler")	数据采样器
data_pipeline/tools/database_inspector.py	依赖base.py	get_data_pipeline_logger("DatabaseInspector")	数据库检查器
data_pipeline/tools/ddl_generator.py	依赖base.py	get_data_pipeline_logger("DDLGenerator")	DDL生成器
data_pipeline/tools/doc_generator.py	依赖base.py	get_data_pipeline_logger("DocGenerator")	文档生成器

3. vanna.log - Vanna相关模块

core目录

文件	当前日志方式	目标Logger	说明
core/vanna_llm_factory.py	无	get_vanna_logger("VannaFactory")	Vanna实例工厂
core/embedding_function.py	无	get_vanna_logger("EmbeddingFunction")	嵌入函数

customllm目录

文件	当前日志方式	目标Logger	说明
customllm/base_llm_chat.py	print	get_vanna_logger("BaseLLMChat")	LLM聊天基类
customllm/deepseek_chat.py	继承base_llm_chat	get_vanna_logger("DeepSeekChat")	DeepSeek聊天实现
customllm/ollama_chat.py	继承base_llm_chat	get_vanna_logger("OllamaChat")	Ollama聊天实现
customllm/qianwen_chat.py	继承base_llm_chat	get_vanna_logger("QianwenChat")	千问聊天实现

customembedding目录

文件	当前日志方式	目标Logger	说明
customembedding/ollama_embedding.py	无	get_vanna_logger("OllamaEmbedding")	Ollama嵌入实现

custompgvector目录

文件	当前日志方式	目标Logger	说明
custompgvector/pgvector.py	logging.info/error	get_vanna_logger("PGVector")	PostgreSQL向量存储

common目录（Vanna相关）

文件	当前日志方式	目标Logger	说明
common/vanna_instance.py	无	get_vanna_logger("VannaInstance")	Vanna实例管理
common/vanna_combinations.py	无	get_vanna_logger("VannaCombinations")	Vanna组合配置

4. app.log - 主应用和通用模块

主应用文件

文件	当前日志方式	目标Logger	说明
citu_app.py	无	get_app_logger("CituApp")	主应用入口
flask_app.py	无	get_app_logger("FlaskApp")	Flask应用（暂不考虑）
chainlit_app.py	无	get_app_logger("ChainlitApp")	Chainlit应用（暂不考虑）
app_config.py	无	无需日志	应用配置

common目录（通用功能）

文件	当前日志方式	目标Logger	说明
common/qa_feedback_manager.py	print	get_app_logger("QAFeedbackManager")	QA反馈管理
common/redis_conversation_manager.py	无	get_app_logger("RedisConversation")	Redis对话管理
common/embedding_cache_manager.py	无	get_app_logger("EmbeddingCache")	嵌入缓存管理
common/session_aware_cache.py	无	get_app_logger("SessionCache")	会话缓存
common/utils.py	无	get_app_logger("CommonUtils")	通用工具
common/messages.py	无	无需日志	消息定义
common/result.py	无	无需日志	结果定义

特殊处理说明

1. data_pipeline/utils/logger.py

当前是data_pipeline模块的日志系统，改造方案：

• 直接删除原有日志系统代码
• 保留函数接口（如setup_logging），但函数体为空或直接pass
• 所有调用该模块的地方直接使用新日志系统

2. print语句替换策略

• 所有 print() 语句根据内容判断日志级别
• 包含 error/exception/fail 的内容 -> logger.error()
• 包含 warning/warn 的内容 -> logger.warning()
• 包含 debug 的内容 -> logger.debug()
• 其他内容 -> logger.info()

3. 现有logging.getLogger替换

• 所有 logging.getLogger("schema_tools.*") 替换为 get_data_pipeline_logger()
• 保持原有的日志级别习惯

实施优先级

1. 第一优先级：citu_app.py 和 agent 模块（核心功能）
2. 第二优先级：data_pipeline 模块（直接改造）
3. 第三优先级：vanna 相关模块
4. 第四优先级：common 通用模块

注意事项

1. 模块分离：4个模块的日志完全独立，各自输出到对应的日志文件
2. 上下文信息：在 agent 模块和 app 模块中支持 user_id 和 session_id（可选）
3. 性能统计：保留原有的时间统计方式，不使用装饰器
4. 直接改造：所有模块直接使用新系统，不考虑向后兼容

测试建议

1. 先在开发环境测试，确保日志正常输出到对应文件
2. 检查日志文件轮转功能是否正常
3. 验证各模块日志是否正确分离
4. 确认错误降级到控制台的功能正常工作