SemIf 接进现有脚本后报错，先别急着改参数或升级依赖包。把报错按发生位置分成“加载阶段失败”和“执行阶段失败”两类，能直接砍掉一半排查范围：加载阶段的报错通常指向依赖、解释器、环境变量和配置路径；执行阶段的报错通常指向调用参数、返回值结构或调用顺序。判断依据是进程有没有真正跑起来、有没有打印出你自己的业务日志，而不是报错文字里有没有出现 SemIf 字样。

接入 SemIf 报错时，先看失败发生在加载阶段还是执行阶段，再决定查依赖还是查参数。加载阶段失败优先核对解释器、依赖版本、环境变量和配置路径；执行阶段失败优先逐项对照必填项、类型和字段命名。用最小脚本单独调用可以快速把业务代码排除在外。在最小复现和参数对照完成前，不建议升级依赖或改动业务主干，因为那会让新的变量掩盖原有问题。

保留完整报错栈和触发命令区分启动失败与运行中失败

排查前先把现场固定下来。只截最后一行 Error 往往丢掉关键信息，因为加载失败的线索通常在 Traceback 顶部，而执行失败的线索在业务函数与调用点之间的交替层里。建议把标准输出和标准错误一起落盘，并同时记录退出码和当时的执行命令。

# 在项目根目录执行，完整保存报错栈与触发命令
cd <项目根目录>
python3 <你的脚本> `--config` <配置路径> 2>&1 | tee semif_error.log
echo "exit=$?"

拿到日志后按下面两条标准先分类，不要跳步：

• 启动失败（加载阶段）：Traceback 最底部是 import 行、模块查找失败、动态库加载失败或配置读取失败；进程没有输出任何业务日志；通常立即以非 0 退出码结束。
• 运行中失败（执行阶段）：Traceback 中能看到你的业务函数和 SemIf 调用点交替出现；报错前已经打印过部分业务日志；异常多为 TypeError、ValueError、KeyError、超时或返回码不符合预期。

这一步的验证方式很朴素：如果把调用 SemIf 的那几行注释掉，脚本能正常跑完前面的逻辑，那基本可以归到执行阶段；如果注释掉之后依然在启动时报错，问题多半不在 SemIf 调用参数上。

用最小脚本单独调用 SemIf 排除业务代码干扰

分类之后，用一个小脚本单独跑一次最小调用，看报错是否复现。它的作用是确认报错是不是由现有脚本的其他逻辑引起的，比如重复初始化、全局配置覆盖、并发调用或者上游数据格式异常。下面只是通用骨架，包名、客户端类名、方法名都按你实际接入的写法替换。

# min_semif_check.py
def main():
    # 占位：按实际包名或模块名替换
    import semif

    # 占位：按实际必填字段替换
    payload = {
        "input": "hello",
    }

    # 占位：按实际初始化方式替换，密钥建议从环境变量读取
    client = semif.Client(api_key="<TOKEN>")

    # 占位：按实际调用方法名替换
    resp = client.call(payload)
    print("type:", type(resp))
    print("resp:", resp)


if __name__ == "__main__":
    main()

执行方式就是 python3 min_semif_check.py。如果最小脚本同样报错，把注意力放回依赖、环境和凭证；如果最小脚本能通过，而原脚本仍失败，那问题在参数组合或业务代码里的调用上下文，建议回到原脚本，逐步注释掉无关分支，对比两次调用入参的差异。注意别把最小脚本放在被 __init__.py、sitecustomize 或 sys.path 注入影响的目录里，否则干扰并没有真正排除。

检查依赖版本、运行环境和配置路径是否与当前脚本一致

加载阶段的报错，绝大多数来自“能跑的环境”和“报错的环境”之间的差异。不要凭印象判断，按下面这张对照表逐项取值并记录，取值命令尽量用脚本当前所处的解释器和虚拟环境执行，而不是另开一个终端。

• 解释器：which python3、python3 -V，确认不是另一个版本的 Python 或另一个虚拟环境。
• 依赖版本：pip show <包名>、pip freeze 导出到文件，和能跑通的环境对比差异项。
• 环境变量：env | grep -i semif，确认密钥、区域、端点、超时等变量在报错环境下是否存在且非空。
• 配置路径：pwd 加配置文件的绝对路径，确认相对路径是相对谁解析的；工作目录变化常表现为“配置项为空”或“找不到文件”。
• 运行载体：本机、容器、虚拟环境还是任务调度器，是否有网络出口限制或超时设置。
• 编码与地区设置：文件编码、LANG 之类的变量是否一致，避免读配置时报解码错误。

对照完成再动手改。风险边界是：不要用“升级到最新依赖”这种方式碰运气，版本变动会引入新的报错，让原本清晰的问题重新变模糊；先用锁定版本的方式复现，再决定是否升级。

逐项对照调用参数确认必填项和类型没有传错

执行阶段的报错，多半是参数层面的问题，而且往往不是“没传”，而是“传了但形态不对”。建议为当前这次调用填一张对照表，参数名以实际接口定义为准，不要凭记忆。

常见的对照结论有三类：必填项缺失或为空字符串；类型不匹配，比如数字型参数从环境变量读取后仍是字符串；命名不一致，比如下划线与驼峰混用、字段名拼写接近但不相同。布尔值尤其容易出错，字符串形式的 false 在多数语言里仍是真值，需要显式转换。验证方式是打印实际传给调用的字典或结构体，而不是打印转换前的原始输入。

把最小复现命令和修复后的验证输出记录下来

问题解决后，把复现命令和验证输出留成一份可交接的记录，下次出现同类报错时可以直接比对，而不是从零再查一遍。复现命令模板建议包含工作目录、解释器、最小脚本、配置路径和日志落盘。

cd <项目根目录>
<python解释器> min_semif_check.py `--config` <配置路径> 2>&1 | tee semif_verify.log
echo "exit=$?"

验证输出里建议至少包含这些字段：执行时间、解释器版本与关键依赖版本、完整命令原文、退出码、关键日志行、返回结构及其中的关键字段、以及与修复前输出的差异点。判断修复是否成立的依据是退出码为 0 且返回结构符合预期，而不是“这次没报错”这一句话。如果只是绕过了某个参数，或临时改用了别的调用方式，把它标注成临时绕行，别写成最终的接入方案。