API 文档

本文档介绍 OCR 评估框架的 API 接口。

核心模块

OCR评估框架

一个专业的OCR模型评估和对比框架，支持多种OCR模型的准确率测试和性能分析。

class ocr_evaluation.Config(config_file: Path | None = None)

基类：object

配置管理类

DEFAULT_CONFIG = {'evaluation': {'accuracy_threshold': 0.95, 'case_sensitive': True, 'use_levenshtein': True}, 'logging': {'file': None, 'format': '%(asctime)s - %(name)s - %(levelname)s - %(message)s', 'level': 'INFO'}, 'models': {'paddleocr': {'lang': 'en', 'use_doc_orientation_classify': False, 'use_doc_unwarping': False, 'use_gpu': False, 'use_textline_orientation': False}, 'qwen_vl': {'lmstudio_url': 'ws://localhost:1234', 'max_tokens': 50, 'model_name': 'qwen/qwen2.5-vl-7b', 'temperature': 0.1}}, 'output': {'report_format': 'markdown', 'reports_dir': 'data/reports', 'results_dir': 'data/outputs'}}

__init__(config_file: Path | None = None)

初始化配置

参数:

config_file – 配置文件路径，如果未指定则使用默认配置

load_config(config_file: Path)

从文件加载配置

参数:

config_file – 配置文件路径，支持YAML和JSON格式

get(key: str, default: Any | None = None) → Any

获取配置值，支持点分割路径

参数:

• key – 配置键，支持嵌套路径如 ‘models.paddleocr.lang’

• default – 默认值

返回:

配置值

set(key: str, value: Any)

设置配置值

参数:

• key – 配置键，支持嵌套路径

• value – 配置值

save_config(config_file: Path | None = None)

保存配置到文件

参数:

config_file – 配置文件路径，如果未指定则使用初始化时的文件

property config: Dict[str, Any]

获取完整配置字典

get_model_config(model_name: str) → Dict[str, Any]

获取指定模型的配置

get_paddleocr_config() → Dict[str, Any]

获取PaddleOCR配置

get_qwen_config() → Dict[str, Any]

获取Qwen配置

get_logging_config() → Dict[str, Any]

获取日志配置

get_output_config() → Dict[str, Any]

获取输出配置

ocr_evaluation.get_config() → Config

获取全局配置实例

ocr_evaluation.set_config(config: Config)

设置全局配置实例

ocr_evaluation.load_config_from_file(config_file: Path) → Config

从文件加载配置并设置为全局配置

class ocr_evaluation.ModelTypes

基类：object

支持的模型类型

PADDLEOCR = 'paddleocr'

QWEN_VL = 'qwen_vl'

classmethod all_types()

class ocr_evaluation.BaseEvaluator(config: Dict[str, Any] | None = None)

基类：ABC

OCR评估器基类

定义了所有OCR模型评估器必须实现的接口

__init__(config: Dict[str, Any] | None = None)

初始化评估器

参数:

config – 模型配置字典

abstract get_model_name() → str

获取模型名称

abstract get_model_type() → str

获取模型类型

abstract initialize() → bool

初始化模型

返回:

初始化是否成功

返回类型:

bool

abstract recognize_image(image_path: Path) → str

识别单张图片

参数:

image_path – 图片路径

返回:

识别结果文本

返回类型:

str

abstract cleanup()

清理资源

validate_image(image_path: Path) → bool

验证图片文件

参数:

image_path – 图片路径

返回:

图片是否有效

返回类型:

bool

parse_label_file(label_file: Path) → Dict[str, str]

解析Label.txt文件

参数:

label_file – 标签文件路径

返回:

图片名到标注文本的映射

返回类型:

Dict[str, str]

calculate_accuracy(ground_truth: str, predicted: str) → float

计算准确率

参数:

• ground_truth – 标准答案

• predicted – 预测结果

返回:

准确率 (0.0 到 1.0)

返回类型:

float

evaluate_directory(directory: Path) → DirectoryResult | None

评估单个目录

参数:

directory – 包含图片和Label.txt的目录

返回:

目录评估结果，如果失败返回None

返回类型:

DirectoryResult

evaluate_dataset(images_dir: Path) → TestSummary | None

评估完整数据集

参数:

images_dir – 包含所有测试图片目录的根目录

返回:

完整测试汇总结果

返回类型:

TestSummary

class ocr_evaluation.EvaluationResult(image_path: Path, ground_truth: str, predicted: str, accuracy: float, exact_match: bool, metadata: Dict[str, Any] | None = None)

基类：object

单个样本评估结果

image_path: Path

ground_truth: str

predicted: str

accuracy: float

exact_match: bool

metadata: Dict[str, Any] | None = None

__init__(image_path: Path, ground_truth: str, predicted: str, accuracy: float, exact_match: bool, metadata: Dict[str, Any] | None = None) → None

class ocr_evaluation.DirectoryResult(directory: Path, total_images: int, average_accuracy: float, exact_match_count: int, exact_match_rate: float, results: List[EvaluationResult], metadata: Dict[str, Any] | None = None)

基类：object

目录评估结果

directory: Path

total_images: int

average_accuracy: float

exact_match_count: int

exact_match_rate: float

results: List[EvaluationResult]

metadata: Dict[str, Any] | None = None

__init__(directory: Path, total_images: int, average_accuracy: float, exact_match_count: int, exact_match_rate: float, results: List[EvaluationResult], metadata: Dict[str, Any] | None = None) → None

class ocr_evaluation.TestSummary(model_name: str, test_timestamp: str, total_images: int, overall_accuracy: float, overall_exact_match_rate: float, directory_results: List[DirectoryResult], technical_details: Dict[str, Any], metadata: Dict[str, Any] | None = None)

基类：object

完整测试汇总结果

model_name: str

test_timestamp: str

total_images: int

overall_accuracy: float

overall_exact_match_rate: float

directory_results: List[DirectoryResult]

technical_details: Dict[str, Any]

metadata: Dict[str, Any] | None = None

__init__(model_name: str, test_timestamp: str, total_images: int, overall_accuracy: float, overall_exact_match_rate: float, directory_results: List[DirectoryResult], technical_details: Dict[str, Any], metadata: Dict[str, Any] | None = None) → None

class ocr_evaluation.PaddleOCREvaluator(config: Dict[str, Any] | None = None)

基类：BaseEvaluator

PaddleOCR评估器

__init__(config: Dict[str, Any] | None = None)

初始化PaddleOCR评估器

参数:

config – PaddleOCR配置参数

get_model_name() → str

获取模型名称

get_model_type() → str

获取模型类型

initialize() → bool

初始化PaddleOCR模型

recognize_image(image_path: Path) → str

使用PaddleOCR识别单张图片

参数:

image_path – 图片路径

返回:

识别的文本结果

返回类型:

str

cleanup()

清理PaddleOCR资源

get_model_info() → Dict[str, Any]

获取模型详细信息

classmethod create_with_optimal_config() → PaddleOCREvaluator

使用最佳配置创建评估器实例

返回:

使用优化配置的评估器实例

返回类型:

PaddleOCREvaluator

classmethod create_from_config_dict(config_dict: Dict[str, Any]) → PaddleOCREvaluator

从配置字典创建评估器实例

参数:

config_dict – 配置字典，通常来自配置文件

返回:

评估器实例

返回类型:

PaddleOCREvaluator

class ocr_evaluation.QwenVLEvaluator(config: Dict[str, Any] | None = None)

基类：BaseEvaluator

Qwen2.5-VL多模态模型评估器

__init__(config: Dict[str, Any] | None = None)

初始化Qwen评估器

参数:

config – Qwen模型配置参数

get_model_name() → str

获取模型名称

get_model_type() → str

获取模型类型

initialize() → bool

初始化Qwen模型

recognize_image(image_path: Path) → str

使用Qwen2.5-VL识别单张图片

参数:

image_path – 图片路径

返回:

识别的文本结果

返回类型:

str

cleanup()

清理Qwen资源

get_model_info() → Dict[str, Any]

获取模型详细信息

test_connection() → bool

测试LMStudio连接

返回:

连接是否成功

返回类型:

bool

classmethod create_with_default_config() → QwenVLEvaluator

使用默认配置创建评估器实例

返回:

使用默认配置的评估器实例

返回类型:

QwenVLEvaluator

classmethod create_from_config_dict(config_dict: Dict[str, Any]) → QwenVLEvaluator

从配置字典创建评估器实例

参数:

config_dict – 配置字典，通常来自配置文件

返回:

评估器实例

返回类型:

QwenVLEvaluator

ocr_evaluation.create_evaluator(model_type: str, config: dict | None = None) → BaseEvaluator

创建指定类型的评估器

参数:

• model_type – 模型类型名称

• config – 模型配置参数

返回:

评估器实例

返回类型:

BaseEvaluator

抛出:

ValueError – 不支持的模型类型

ocr_evaluation.get_supported_models() → list

获取支持的模型类型列表

class ocr_evaluation.ReportGenerator(output_dir: Path | None = None)

基类：object

报告生成器

__init__(output_dir: Path | None = None)

初始化报告生成器

参数:

output_dir – 报告输出目录

generate_markdown_report(summary: TestSummary) → str

生成Markdown格式报告

参数:

summary – 测试汇总结果

返回:

Markdown格式的报告内容

返回类型:

str

save_markdown_report(summary: TestSummary, filename: str | None = None) → Path

保存Markdown报告到文件

参数:

• summary – 测试汇总结果

• filename – 文件名，如果未指定则自动生成

返回:

保存的文件路径

返回类型:

Path

save_json_results(summary: TestSummary, filename: str | None = None) → Path

保存JSON格式的详细结果

参数:

• summary – 测试汇总结果

• filename – 文件名，如果未指定则自动生成

返回:

保存的文件路径

返回类型:

Path

ocr_evaluation.get_logger(name: str | None = None) → Logger

获取全局日志器

参数:

name – 子日志器名称

返回:

日志器实例

返回类型:

logging.Logger

ocr_evaluation.setup_logging(config: Dict[str, Any])

设置全局日志配置

参数:

config – 日志配置

ocr_evaluation.evaluate_model(model_type: str, images_dir: str, config: dict | None = None) → TestSummary

便捷的模型评估函数

参数:

• model_type – 模型类型 (‘paddleocr’ 或 ‘qwen_vl’)

• images_dir – 图片目录路径

• config – 可选的模型配置

返回:

评估结果汇总

返回类型:

TestSummary

示例

>>> from ocr_evaluation import evaluate_model
>>> summary = evaluate_model('paddleocr', './images')
>>> print(f"准确率: {summary.overall_accuracy:.2%}")

ocr_evaluation.generate_report(summary: TestSummary, output_dir: str = './reports', format: str = 'markdown') → str

便捷的报告生成函数

参数:

• summary – 评估结果汇总

• output_dir – 输出目录

• format – 报告格式 (‘markdown’ 或 ‘json’)

返回:

生成的报告文件路径

返回类型:

str

示例

>>> from ocr_evaluation import evaluate_model, generate_report
>>> summary = evaluate_model('paddleocr', './images')
>>> report_path = generate_report(summary)
>>> print(f"报告已保存至: {report_path}")

配置模块

OCR评估框架配置模块

class ocr_evaluation.config.Config(config_file: Path | None = None)

基类：object

配置管理类

DEFAULT_CONFIG = {'evaluation': {'accuracy_threshold': 0.95, 'case_sensitive': True, 'use_levenshtein': True}, 'logging': {'file': None, 'format': '%(asctime)s - %(name)s - %(levelname)s - %(message)s', 'level': 'INFO'}, 'models': {'paddleocr': {'lang': 'en', 'use_doc_orientation_classify': False, 'use_doc_unwarping': False, 'use_gpu': False, 'use_textline_orientation': False}, 'qwen_vl': {'lmstudio_url': 'ws://localhost:1234', 'max_tokens': 50, 'model_name': 'qwen/qwen2.5-vl-7b', 'temperature': 0.1}}, 'output': {'report_format': 'markdown', 'reports_dir': 'data/reports', 'results_dir': 'data/outputs'}}

__init__(config_file: Path | None = None)

初始化配置

参数:

config_file – 配置文件路径，如果未指定则使用默认配置

load_config(config_file: Path)

从文件加载配置

参数:

config_file – 配置文件路径，支持YAML和JSON格式

get(key: str, default: Any | None = None) → Any

获取配置值，支持点分割路径

参数:

• key – 配置键，支持嵌套路径如 ‘models.paddleocr.lang’

• default – 默认值

返回:

配置值

set(key: str, value: Any)

设置配置值

参数:

• key – 配置键，支持嵌套路径

• value – 配置值

save_config(config_file: Path | None = None)

保存配置到文件

参数:

config_file – 配置文件路径，如果未指定则使用初始化时的文件

property config: Dict[str, Any]

获取完整配置字典

get_model_config(model_name: str) → Dict[str, Any]

获取指定模型的配置

get_paddleocr_config() → Dict[str, Any]

获取PaddleOCR配置

get_qwen_config() → Dict[str, Any]

获取Qwen配置

get_logging_config() → Dict[str, Any]

获取日志配置

get_output_config() → Dict[str, Any]

获取输出配置

ocr_evaluation.config.get_config() → Config

获取全局配置实例

ocr_evaluation.config.set_config(config: Config)

设置全局配置实例

ocr_evaluation.config.load_config_from_file(config_file: Path) → Config

从文件加载配置并设置为全局配置

class ocr_evaluation.config.ModelTypes

基类：object

支持的模型类型

PADDLEOCR = 'paddleocr'

QWEN_VL = 'qwen_vl'

classmethod all_types()

class ocr_evaluation.config.PaddleOCRConstants

基类：object

PaddleOCR相关常量

DEFAULT_LANG = 'en'

SUPPORTED_LANGS = ['ch', 'en', 'fr', 'german', 'korean', 'japan']

OPTIMIZED_CONFIG = {'lang': 'en', 'use_doc_orientation_classify': False, 'use_doc_unwarping': False, 'use_textline_orientation': False}

class ocr_evaluation.config.QwenConstants

基类：object

Qwen2.5-VL相关常量

DEFAULT_MODEL_NAME = 'qwen/qwen2.5-vl-7b'

DEFAULT_LMSTUDIO_URL = 'ws://localhost:1234'

DEFAULT_TEMPERATURE = 0.1

DEFAULT_MAX_TOKENS = 50

DEFAULT_PROMPT = 'Please look at this image carefully and extract the exact text/code shown in the image. This appears to be an alphanumeric code or product number. Please provide ONLY the exact text you see, without any additional explanation or formatting. The text typically consists of letters, numbers, and may include symbols like # or .'

class ocr_evaluation.config.EvaluationConstants

基类：object

评估相关常量

DEFAULT_ACCURACY_THRESHOLD = 0.95

ACCURACY_RANGES = {'0.6-0.7': (0.6, 0.7), '0.7-0.8': (0.7, 0.8), '0.8-0.9': (0.8, 0.9), '0.9-1.0': (0.9, 1.0), '<0.6': (0.0, 0.6)}

class ocr_evaluation.config.TextProcessingConstants

基类：object

文本处理相关常量

ALPHANUMERIC_PATTERN = re.compile('[A-Z0-9]+[#.\\-A-Z0-9]*')

EXPLANATION_PREFIXES = ['The text shown in the image is:', 'The code in the image is:', 'The text appears to be:', 'I can see:', 'The image shows:', 'The alphanumeric code is:', 'The product number is:', 'Looking at this image, I can see:']

QUOTE_CHARS = '"\'`'

class ocr_evaluation.config.LoggingConstants

基类：object

日志相关常量

DEFAULT_FORMAT = '%(asctime)s - %(name)s - %(levelname)s - %(message)s'

DEFAULT_LEVEL = 'INFO'

SUPPORTED_LEVELS = ['DEBUG', 'INFO', 'WARNING', 'ERROR', 'CRITICAL']

class ocr_evaluation.config.ReportConstants

基类：object

报告生成相关常量

MARKDOWN_EXTENSION = '.md'

JSON_EXTENSION = '.json'

HTML_EXTENSION = '.html'

DEFAULT_REPORT_NAME_TEMPLATE = '{model}_准确率报告_{timestamp}'

DEFAULT_RESULTS_NAME_TEMPLATE = '{model}_results_{timestamp}'

REPORT_TIMESTAMP_FORMAT = '%Y-%m-%d_%H-%M-%S'

DISPLAY_TIMESTAMP_FORMAT = '%Y-%m-%d %H:%M:%S'

class ocr_evaluation.config.ErrorCodes

基类：object

错误码定义

SUCCESS = 0

CONFIG_ERROR = 1

MODEL_INIT_ERROR = 2

DATA_ERROR = 3

EVALUATION_ERROR = 4

REPORT_ERROR = 5

UNKNOWN_ERROR = 99

class ocr_evaluation.config.PerformanceConstants

基类：object

性能相关常量

DEFAULT_BATCH_SIZE = 1

MAX_IMAGE_SIZE = 10485760

TIMEOUT_SECONDS = 30

class ocr_evaluation.config.EnvVars

基类：object

环境变量名称

CONFIG_FILE = 'OCR_EVALUATION_CONFIG'

LOG_LEVEL = 'OCR_EVALUATION_LOG_LEVEL'

OUTPUT_DIR = 'OCR_EVALUATION_OUTPUT_DIR'

LMSTUDIO_URL = 'LMSTUDIO_URL'

USE_GPU = 'OCR_EVALUATION_USE_GPU'

设置模块

OCR评估框架配置管理模块

class ocr_evaluation.config.settings.Config(config_file: Path | None = None)

基类：object

配置管理类

DEFAULT_CONFIG = {'evaluation': {'accuracy_threshold': 0.95, 'case_sensitive': True, 'use_levenshtein': True}, 'logging': {'file': None, 'format': '%(asctime)s - %(name)s - %(levelname)s - %(message)s', 'level': 'INFO'}, 'models': {'paddleocr': {'lang': 'en', 'use_doc_orientation_classify': False, 'use_doc_unwarping': False, 'use_gpu': False, 'use_textline_orientation': False}, 'qwen_vl': {'lmstudio_url': 'ws://localhost:1234', 'max_tokens': 50, 'model_name': 'qwen/qwen2.5-vl-7b', 'temperature': 0.1}}, 'output': {'report_format': 'markdown', 'reports_dir': 'data/reports', 'results_dir': 'data/outputs'}}

__init__(config_file: Path | None = None)

初始化配置

参数:

config_file – 配置文件路径，如果未指定则使用默认配置

load_config(config_file: Path)

从文件加载配置

参数:

config_file – 配置文件路径，支持YAML和JSON格式

get(key: str, default: Any | None = None) → Any

获取配置值，支持点分割路径

参数:

• key – 配置键，支持嵌套路径如 ‘models.paddleocr.lang’

• default – 默认值

返回:

配置值

set(key: str, value: Any)

设置配置值

参数:

• key – 配置键，支持嵌套路径

• value – 配置值

save_config(config_file: Path | None = None)

保存配置到文件

参数:

config_file – 配置文件路径，如果未指定则使用初始化时的文件

property config: Dict[str, Any]

获取完整配置字典

get_model_config(model_name: str) → Dict[str, Any]

获取指定模型的配置

get_paddleocr_config() → Dict[str, Any]

获取PaddleOCR配置

get_qwen_config() → Dict[str, Any]

获取Qwen配置

get_logging_config() → Dict[str, Any]

获取日志配置

get_output_config() → Dict[str, Any]

获取输出配置

ocr_evaluation.config.settings.get_config() → Config

获取全局配置实例

ocr_evaluation.config.settings.set_config(config: Config)

设置全局配置实例

ocr_evaluation.config.settings.load_config_from_file(config_file: Path) → Config

从文件加载配置并设置为全局配置

常量模块

OCR评估框架常量定义

class ocr_evaluation.config.constants.ModelTypes

基类：object

支持的模型类型

PADDLEOCR = 'paddleocr'

QWEN_VL = 'qwen_vl'

classmethod all_types()

class ocr_evaluation.config.constants.PaddleOCRConstants

基类：object

PaddleOCR相关常量

DEFAULT_LANG = 'en'

SUPPORTED_LANGS = ['ch', 'en', 'fr', 'german', 'korean', 'japan']

OPTIMIZED_CONFIG = {'lang': 'en', 'use_doc_orientation_classify': False, 'use_doc_unwarping': False, 'use_textline_orientation': False}

class ocr_evaluation.config.constants.QwenConstants

基类：object

Qwen2.5-VL相关常量

DEFAULT_MODEL_NAME = 'qwen/qwen2.5-vl-7b'

DEFAULT_LMSTUDIO_URL = 'ws://localhost:1234'

DEFAULT_TEMPERATURE = 0.1

DEFAULT_MAX_TOKENS = 50

DEFAULT_PROMPT = 'Please look at this image carefully and extract the exact text/code shown in the image. This appears to be an alphanumeric code or product number. Please provide ONLY the exact text you see, without any additional explanation or formatting. The text typically consists of letters, numbers, and may include symbols like # or .'

class ocr_evaluation.config.constants.EvaluationConstants

基类：object

评估相关常量

DEFAULT_ACCURACY_THRESHOLD = 0.95

ACCURACY_RANGES = {'0.6-0.7': (0.6, 0.7), '0.7-0.8': (0.7, 0.8), '0.8-0.9': (0.8, 0.9), '0.9-1.0': (0.9, 1.0), '<0.6': (0.0, 0.6)}

class ocr_evaluation.config.constants.TextProcessingConstants

基类：object

文本处理相关常量

ALPHANUMERIC_PATTERN = re.compile('[A-Z0-9]+[#.\\-A-Z0-9]*')

EXPLANATION_PREFIXES = ['The text shown in the image is:', 'The code in the image is:', 'The text appears to be:', 'I can see:', 'The image shows:', 'The alphanumeric code is:', 'The product number is:', 'Looking at this image, I can see:']

QUOTE_CHARS = '"\'`'

class ocr_evaluation.config.constants.LoggingConstants

基类：object

日志相关常量

DEFAULT_FORMAT = '%(asctime)s - %(name)s - %(levelname)s - %(message)s'

DEFAULT_LEVEL = 'INFO'

SUPPORTED_LEVELS = ['DEBUG', 'INFO', 'WARNING', 'ERROR', 'CRITICAL']

class ocr_evaluation.config.constants.ReportConstants

基类：object

报告生成相关常量

MARKDOWN_EXTENSION = '.md'

JSON_EXTENSION = '.json'

HTML_EXTENSION = '.html'

DEFAULT_REPORT_NAME_TEMPLATE = '{model}_准确率报告_{timestamp}'

DEFAULT_RESULTS_NAME_TEMPLATE = '{model}_results_{timestamp}'

REPORT_TIMESTAMP_FORMAT = '%Y-%m-%d_%H-%M-%S'

DISPLAY_TIMESTAMP_FORMAT = '%Y-%m-%d %H:%M:%S'

class ocr_evaluation.config.constants.ErrorCodes

基类：object

错误码定义

SUCCESS = 0

CONFIG_ERROR = 1

MODEL_INIT_ERROR = 2

DATA_ERROR = 3

EVALUATION_ERROR = 4

REPORT_ERROR = 5

UNKNOWN_ERROR = 99

class ocr_evaluation.config.constants.PerformanceConstants

基类：object

性能相关常量

DEFAULT_BATCH_SIZE = 1

MAX_IMAGE_SIZE = 10485760

TIMEOUT_SECONDS = 30

class ocr_evaluation.config.constants.EnvVars

基类：object

环境变量名称

CONFIG_FILE = 'OCR_EVALUATION_CONFIG'

LOG_LEVEL = 'OCR_EVALUATION_LOG_LEVEL'

OUTPUT_DIR = 'OCR_EVALUATION_OUTPUT_DIR'

LMSTUDIO_URL = 'LMSTUDIO_URL'

USE_GPU = 'OCR_EVALUATION_USE_GPU'

模型模块

基础评估器

OCR评估器抽象基类

class ocr_evaluation.models.base.EvaluationResult(image_path: Path, ground_truth: str, predicted: str, accuracy: float, exact_match: bool, metadata: Dict[str, Any] | None = None)

基类：object

单个样本评估结果

image_path: Path

ground_truth: str

predicted: str

accuracy: float

exact_match: bool

metadata: Dict[str, Any] | None = None

__init__(image_path: Path, ground_truth: str, predicted: str, accuracy: float, exact_match: bool, metadata: Dict[str, Any] | None = None) → None

class ocr_evaluation.models.base.DirectoryResult(directory: Path, total_images: int, average_accuracy: float, exact_match_count: int, exact_match_rate: float, results: List[EvaluationResult], metadata: Dict[str, Any] | None = None)

基类：object

目录评估结果

directory: Path

total_images: int

average_accuracy: float

exact_match_count: int

exact_match_rate: float

results: List[EvaluationResult]

metadata: Dict[str, Any] | None = None

__init__(directory: Path, total_images: int, average_accuracy: float, exact_match_count: int, exact_match_rate: float, results: List[EvaluationResult], metadata: Dict[str, Any] | None = None) → None

class ocr_evaluation.models.base.TestSummary(model_name: str, test_timestamp: str, total_images: int, overall_accuracy: float, overall_exact_match_rate: float, directory_results: List[DirectoryResult], technical_details: Dict[str, Any], metadata: Dict[str, Any] | None = None)

基类：object

完整测试汇总结果

model_name: str

test_timestamp: str

total_images: int

overall_accuracy: float

overall_exact_match_rate: float

directory_results: List[DirectoryResult]

technical_details: Dict[str, Any]

metadata: Dict[str, Any] | None = None

__init__(model_name: str, test_timestamp: str, total_images: int, overall_accuracy: float, overall_exact_match_rate: float, directory_results: List[DirectoryResult], technical_details: Dict[str, Any], metadata: Dict[str, Any] | None = None) → None

class ocr_evaluation.models.base.BaseEvaluator(config: Dict[str, Any] | None = None)

基类：ABC

OCR评估器基类

定义了所有OCR模型评估器必须实现的接口

__init__(config: Dict[str, Any] | None = None)

初始化评估器

参数:

config – 模型配置字典

abstract get_model_name() → str

获取模型名称

abstract get_model_type() → str

获取模型类型

abstract initialize() → bool

初始化模型

返回:

初始化是否成功

返回类型:

bool

abstract recognize_image(image_path: Path) → str

识别单张图片

参数:

image_path – 图片路径

返回:

识别结果文本

返回类型:

str

abstract cleanup()

清理资源

validate_image(image_path: Path) → bool

验证图片文件

参数:

image_path – 图片路径

返回:

图片是否有效

返回类型:

bool

parse_label_file(label_file: Path) → Dict[str, str]

解析Label.txt文件

参数:

label_file – 标签文件路径

返回:

图片名到标注文本的映射

返回类型:

Dict[str, str]

calculate_accuracy(ground_truth: str, predicted: str) → float

计算准确率

参数:

• ground_truth – 标准答案

• predicted – 预测结果

返回:

准确率 (0.0 到 1.0)

返回类型:

float

evaluate_directory(directory: Path) → DirectoryResult | None

评估单个目录

参数:

directory – 包含图片和Label.txt的目录

返回:

目录评估结果，如果失败返回None

返回类型:

DirectoryResult

evaluate_dataset(images_dir: Path) → TestSummary | None

评估完整数据集

参数:

images_dir – 包含所有测试图片目录的根目录

返回:

完整测试汇总结果

返回类型:

TestSummary

PaddleOCR 评估器

PaddleOCR评估器实现

class ocr_evaluation.models.paddleocr_evaluator.PaddleOCREvaluator(config: Dict[str, Any] | None = None)

基类：BaseEvaluator

PaddleOCR评估器

__init__(config: Dict[str, Any] | None = None)

初始化PaddleOCR评估器

参数:

config – PaddleOCR配置参数

get_model_name() → str

获取模型名称

get_model_type() → str

获取模型类型

initialize() → bool

初始化PaddleOCR模型

recognize_image(image_path: Path) → str

使用PaddleOCR识别单张图片

参数:

image_path – 图片路径

返回:

识别的文本结果

返回类型:

str

cleanup()

清理PaddleOCR资源

get_model_info() → Dict[str, Any]

获取模型详细信息

classmethod create_with_optimal_config() → PaddleOCREvaluator

使用最佳配置创建评估器实例

返回:

使用优化配置的评估器实例

返回类型:

PaddleOCREvaluator

classmethod create_from_config_dict(config_dict: Dict[str, Any]) → PaddleOCREvaluator

从配置字典创建评估器实例

参数:

config_dict – 配置字典，通常来自配置文件

返回:

评估器实例

返回类型:

PaddleOCREvaluator

Qwen 评估器

Qwen2.5-VL评估器实现

class ocr_evaluation.models.qwen_evaluator.QwenVLEvaluator(config: Dict[str, Any] | None = None)

基类：BaseEvaluator

Qwen2.5-VL多模态模型评估器

__init__(config: Dict[str, Any] | None = None)

初始化Qwen评估器

参数:

config – Qwen模型配置参数

get_model_name() → str

获取模型名称

get_model_type() → str

获取模型类型

initialize() → bool

初始化Qwen模型

recognize_image(image_path: Path) → str

使用Qwen2.5-VL识别单张图片

参数:

image_path – 图片路径

返回:

识别的文本结果

返回类型:

str

cleanup()

清理Qwen资源

get_model_info() → Dict[str, Any]

获取模型详细信息

test_connection() → bool

测试LMStudio连接

返回:

连接是否成功

返回类型:

bool

classmethod create_with_default_config() → QwenVLEvaluator

使用默认配置创建评估器实例

返回:

使用默认配置的评估器实例

返回类型:

QwenVLEvaluator

classmethod create_from_config_dict(config_dict: Dict[str, Any]) → QwenVLEvaluator

从配置字典创建评估器实例

参数:

config_dict – 配置字典，通常来自配置文件

返回:

评估器实例

返回类型:

QwenVLEvaluator

工具模块

日志工具

日志工具模块

class ocr_evaluation.utils.logging_utils.ColoredFormatter(fmt=None, datefmt=None, style='%', validate=True)

基类：Formatter

带颜色的日志格式化器（仅在控制台使用）

COLORS = {'CRITICAL': '\x1b[35m', 'DEBUG': '\x1b[36m', 'ERROR': '\x1b[31m', 'INFO': '\x1b[32m', 'WARNING': '\x1b[33m'}

RESET = '\x1b[0m'

format(record)

Format the specified record as text.

The record’s attribute dictionary is used as the operand to a string formatting operation which yields the returned string. Before formatting the dictionary, a couple of preparatory steps are carried out. The message attribute of the record is computed using LogRecord.getMessage(). If the formatting string uses the time (as determined by a call to usesTime(), formatTime() is called to format the event time. If there is exception information, it is formatted using formatException() and appended to the message.

class ocr_evaluation.utils.logging_utils.OCRLogger(name: str = 'ocr_evaluation')

基类：object

OCR评估框架统一日志管理器

__init__(name: str = 'ocr_evaluation')

初始化日志管理器

参数:

name – 日志器名称

configure(config: Dict[str, Any] | None = None)

配置日志系统

参数:

config – 日志配置字典

get_logger(name: str | None = None) → Logger

获取子日志器

参数:

name – 子日志器名称，如果未指定则返回主日志器

返回:

日志器实例

返回类型:

logging.Logger

classmethod setup_from_config(config: Dict[str, Any]) → OCRLogger

从配置字典创建日志管理器

参数:

config – 配置字典

返回:

配置好的日志管理器

返回类型:

OCRLogger

class ocr_evaluation.utils.logging_utils.LogContextManager(logger: Logger, level: int)

基类：object

日志上下文管理器，用于临时改变日志级别

__init__(logger: Logger, level: int)

初始化上下文管理器

参数:

• logger – 要管理的日志器

• level – 临时设置的级别

class ocr_evaluation.utils.logging_utils.ProgressLogger(logger: Logger, total: int)

基类：object

进度日志器，用于显示评估进度

__init__(logger: Logger, total: int)

初始化进度日志器

参数:

• logger – 底层日志器

• total – 总任务数

update(message: str = '')

更新进度

参数:

message – 可选的进度消息

finish(message: str = '完成')

完成进度

参数:

message – 完成消息

ocr_evaluation.utils.logging_utils.get_logger(name: str | None = None) → Logger

获取全局日志器

参数:

name – 子日志器名称

返回:

日志器实例

返回类型:

logging.Logger

ocr_evaluation.utils.logging_utils.setup_logging(config: Dict[str, Any])

设置全局日志配置

参数:

config – 日志配置

ocr_evaluation.utils.logging_utils.with_log_level(logger: Logger, level: int) → LogContextManager

临时改变日志级别的上下文管理器

参数:

• logger – 日志器

• level – 临时级别

返回:

上下文管理器

返回类型:

LogContextManager

ocr_evaluation.utils.logging_utils.create_progress_logger(logger: Logger, total: int) → ProgressLogger

创建进度日志器

参数:

• logger – 底层日志器

• total – 总任务数

返回:

进度日志器

返回类型:

ProgressLogger

报告生成器

报告生成工具

class ocr_evaluation.utils.report_generator.ReportGenerator(output_dir: Path | None = None)

基类：object

报告生成器

__init__(output_dir: Path | None = None)

初始化报告生成器

参数:

output_dir – 报告输出目录

generate_markdown_report(summary: TestSummary) → str

生成Markdown格式报告

参数:

summary – 测试汇总结果

返回:

Markdown格式的报告内容

返回类型:

str

save_markdown_report(summary: TestSummary, filename: str | None = None) → Path

保存Markdown报告到文件

参数:

• summary – 测试汇总结果

• filename – 文件名，如果未指定则自动生成

返回:

保存的文件路径

返回类型:

Path

save_json_results(summary: TestSummary, filename: str | None = None) → Path

保存JSON格式的详细结果

参数:

• summary – 测试汇总结果

• filename – 文件名，如果未指定则自动生成

返回:

保存的文件路径

返回类型:

Path

命令行接口

主程序

OCR评估框架主CLI入口

ocr_evaluation.cli.main.create_cli_parser() → ArgumentParser

创建CLI参数解析器

ocr_evaluation.cli.main.show_welcome()

显示欢迎信息

ocr_evaluation.cli.main.show_help_hint(parser: ArgumentParser)

显示帮助提示

ocr_evaluation.cli.main.validate_project_structure(project_root: Path) → bool

验证项目结构

ocr_evaluation.cli.main.setup_project_environment(project_root: Path | None = None)

设置项目环境

ocr_evaluation.cli.main.main(argv: List[str] | None = None) → int

主入口函数

参数:

argv – 命令行参数列表，如果为None则使用sys.argv[1:]

返回:

退出码，0表示成功，非0表示失败

返回类型:

int

ocr_evaluation.cli.main.cli_entry()

CLI入口点，用于setuptools entry_points

命令模块

CLI命令实现

class ocr_evaluation.cli.commands.BaseCommand

基类：object

命令基类

__init__()

setup_logging(args)

设置日志系统

add_common_arguments(parser: ArgumentParser)

添加通用参数

load_config(args)

加载配置

class ocr_evaluation.cli.commands.EvaluateCommand

基类：BaseCommand

评估命令

static add_arguments(parser: ArgumentParser)

添加评估命令参数

run(args)

执行评估命令

class ocr_evaluation.cli.commands.CompareCommand

基类：BaseCommand

模型对比命令

static add_arguments(parser: ArgumentParser)

添加对比命令参数

run(args)

执行模型对比命令

class ocr_evaluation.cli.commands.ConfigCommand

基类：BaseCommand

配置管理命令

static add_arguments(parser: ArgumentParser)

添加配置命令参数

run(args)

执行配置命令

使用示例

基本使用

from ocr_evaluation import OCREvaluator
from ocr_evaluation.config.settings import Settings

# 加载配置
settings = Settings.from_yaml("config.yaml")

# 创建评估器
evaluator = OCREvaluator(settings)

# 运行评估
results = evaluator.evaluate()

# 生成报告
evaluator.generate_report(results)

自定义评估器

from ocr_evaluation.models.base import BaseEvaluator

class CustomEvaluator(BaseEvaluator):
    def __init__(self, config):
        super().__init__(config)
        # 初始化自定义模型

    def recognize_text(self, image_path):
        # 实现文本识别逻辑
        return recognized_text

    def evaluate_single(self, image_path, ground_truth):
        # 实现单张图片评估逻辑
        return evaluation_result

配置管理

from ocr_evaluation.config.settings import Settings

# 从文件加载配置
settings = Settings.from_yaml("config.yaml")

# 从字典创建配置
config_dict = {
    "data": {
        "images_dir": "data/images",
        "ground_truth_file": "data/ground_truth.json"
    },
    "evaluators": [
        {
            "name": "paddleocr",
            "type": "paddleocr",
            "config": {"lang": "ch"}
        }
    ]
}
settings = Settings.from_dict(config_dict)

# 保存配置
settings.save_yaml("new_config.yaml")

日志配置

from ocr_evaluation.utils.logging_utils import setup_logging

# 设置日志
logger = setup_logging(
    level="INFO",
    log_file="evaluation.log",
    format="%(asctime)s - %(name)s - %(levelname)s - %(message)s"
)

# 使用日志
logger.info("开始评估")
logger.error("评估失败")

报告生成

from ocr_evaluation.utils.report_generator import ReportGenerator

# 创建报告生成器
generator = ReportGenerator()

# 生成 HTML 报告
generator.generate_html_report(results, "report.html")

# 生成 JSON 报告
generator.generate_json_report(results, "report.json")

# 生成 CSV 报告
generator.generate_csv_report(results, "report.csv")