私有化助手函数的核心作用是通过职责分离、按需加载和上下文隔离提升主业务逻辑的轻量性、稳定性与可维护性；明确边界、延迟加载、状态外置、流式处理及运行时隔离是其关键实践。

私有化助手函数的核心作用，不是单纯“把代码搬进新文件”，而是通过职责分离、按需加载和上下文隔离，让主业务逻辑更轻、更稳、更易维护。

明确边界：只暴露必要接口，隐藏实现细节

助手函数不应承担业务决策，只做确定性、可复用的原子操作。比如处理PDF解析、日期标准化、敏感字段脱敏等任务，主逻辑只需调用 parse_pdf_content(path) 或 anonymize_phone(text)，而不关心OCR引擎选型或正则规则版本。

• 函数签名保持稳定，内部模型/库升级不影响上层调用
• 避免在助手函数中读取全局配置或直接写数据库——这些应由主流程注入
• 错误类型统一包装（如 AssistantError），不向上抛出底层异常（如 PyPDFiumError）

延迟加载与模块懒实例化

很多助手能力（如OCR、语音转写、大模型推理）依赖重型依赖或GPU资源，但并非每次请求都需要。私有化部署时，应默认关闭常驻，按需启动。

• 使用函数级装饰器控制加载时机，例如：@lazy_init("ocr_engine") 修饰 run_ocr()，首次调用才初始化模型
• 对内存敏感场景（如Mac本地部署CodeLlama），可设置 model_unload_after_idle=60s，空闲后自动释放显存
• 避免在模块顶层 import torch / transformers —— 改为函数内 import，防止冷启动时加载全部权重

状态外置 + 流式处理

助手函数本身不该保存中间状态（如缓存PDF页对象、累积日志列表）。主逻辑负责生命周期管理，助手只做“输入→输出”转换。

• 需要缓存时，由主流程传入 cache_store 实例（如 RedisClient 或 LRUCache），助手只调用 .get(key)/.set(key, value)
• 处理大文件时，助手函数支持生成器返回（yield chunk），主逻辑逐块消费，避免一次性载入整份文档到内存
• 日志、指标、审计追踪等横切关注点，通过参数传入 logger 或 tracer 对象，不内置日志语句

运行时隔离：进程/容器级拆分（适用于生产环境）

当助手能力差异大（如一个要GPU，一个纯CPU；一个需访问内网DB，一个只调外部API），可将不同类别的助手函数部署为独立服务，主业务通过轻量HTTP/gRPC调用。

• 例如：PDF解析服务跑在带GPU的节点，OCR服务单独部署，主Web服务仅发起 POST /v1/parse
• 配合健康检查与熔断（如 tenacity 库），失败时降级为本地简易解析，不阻塞主流程
• 内存占用从“所有助手常驻主进程”变为“仅当前请求涉及的服务实例存活”，整体更可控