TypeError: SpacyNlpEngine.__init__() got an unexpected keyword argument model_config

在AI基础设施和大规模NLP流水线部署中，Apache Spark NLP (John Snow Labs) 是一个常用的高性能工具。然而，在进行版本升级或跨环境迁移时，开发者经常会遇到依赖冲突和初始化错误。其中一个常见且令人困惑的错误是 TypeError: SpacyNlpEngine.__init__() got an unexpected keyword argument model_config。

1. 错误诊断：为什么会出现 model_config 异常？

这个 TypeError 并非直接由你的代码逻辑错误引起，而是发生在 Spark NLP 库的内部组件初始化过程中。SpacyNlpEngine 是 Spark NLP 用于内部处理或集成某些外部NLP功能（尽管名称包含 Spacy，但它是一个内部组件）时使用的类。

核心原因在于版本不匹配 (Version Mismatch)：

1. 旧版API残留： 你可能正在运行一个较新版本的 Spark NLP (例如 4.x)，但其依赖的环境（如某个内部JAR包或缓存）仍在使用旧版（如 3.x 或更早版本）的 SpacyNlpEngine 定义。旧版本的 __init__ 方法不接受 model_config 关键字参数，但新版上游调用方却尝试传入它。
2. 依赖冲突： 当你在环境中同时加载了多个版本的 Spark NLP JAR 包，或者使用了第三方库（如 spark-nlp-jsl 或其他自定义组件）时，这些组件可能依赖于不同版本的 Spark NLP 核心，导致类路径混乱。

2. 解决方案：严格控制依赖项和初始化

解决此类问题的关键在于建立一个干净、版本严格匹配的运行环境。我们通常推荐使用 sparknlp.start() 方法，并明确指定所需的 Spark NLP 和 Spark 版本。

步骤 A: 确认版本兼容性

首先，检查 John Snow Labs 的官方文档，确认你使用的 Spark NLP 版本与你的 Apache Spark 版本是兼容的。

步骤 B: 使用统一的初始化方法 (PySpark)

我们应该避免手动配置 Spark 依赖，而是让 sparknlp.start() 自动处理依赖项的下载和配置，确保所有内部组件都加载了正确的版本。

下面的 PySpark 代码演示了如何初始化一个干净且版本受控的 Spark 会话：

# 确保你的环境中安装了 pyspark 和 spark-nlp
# pip install pyspark spark-nlp

import sparknlp
from pyspark.sql import SparkSession

# 定义你希望使用的严格版本
# 示例: 确保 Spark NLP 4.x 系列与 Spark 3.x 系列兼容
SPARK_NLP_VERSION = "4.4.4" 
SPARK_VERSION = "3.4.1"

try:
    print(f"Initializing Spark Session with Spark NLP {SPARK_NLP_VERSION} and Spark {SPARK_VERSION}")

    # 使用 sparknlp.start() 确保依赖项自动且正确加载
    # 这一步对于解决内部类初始化冲突至关重要
    spark = sparknlp.start(
        spark_nlp_version=SPARK_NLP_VERSION,
        spark_version=SPARK_VERSION
    )

    print("Spark Session Initialized Successfully.")
    print(f"Spark NLP Version: {sparknlp.version()}")
    print(f"Spark Context:")
    spark.sparkContext.getConf().getAll()

    # 示例：运行一个简单的 NLP 任务，验证环境是否正常
    from sparknlp.base import DocumentAssembler
    doc_assembler = DocumentAssembler().setInputCol("text").setOutputCol("document")

    test_data = spark.createDataFrame([("Spark NLP is fast and scalable.",)]).toDF("text")
    processed_df = doc_assembler.transform(test_data)
    processed_df.show(truncate=False)

    spark.stop()

except Exception as e:
    print(f"Initialization Failed: {e}")
    # 如果仍然报错，可能需要检查环境的 Maven 仓库缓存 (如 ~/.m2/repository)

步骤 C: 针对 Spark-Submit/Cluster 部署

如果你在生产环境中使用 spark-submit 部署，必须确保在提交命令中明确指定依赖包的版本，并且只包含一套依赖。

错误的示例 (可能导致冲突):

# 错误: 同时在环境中加载了多套依赖或版本不匹配
# spark-submit --packages com.johnsnowlabs.nlp:spark-nlp_2.12:3.4.0,org.apache.spark:spark-core_2.12:3.2.0 ...

正确的 **spark-submit 示例 (使用最新兼容版本):**

# 假设使用 Spark NLP 4.4.4 和 Spark 3.4.1

spark-submit \
    --packages com.johnsnowlabs.nlp:spark-nlp_2.12:4.4.4 \
    --repositories https://pypi.org/simple \
    your_application.py

3. 额外排查：环境清理

如果上述步骤未能解决问题，这意味着旧的依赖项可能仍在系统缓存中残留：

1. 清除 Maven/Ivy 缓存： Spark 会使用本地缓存来存储依赖项。手动清除用户目录下的 .ivy2 和 .m2 文件夹（如果使用 Maven）可以强制 Spark 重新下载正确的依赖。
2. 检查驱动器配置： 如果在 Databricks 或 EMR 等集群环境中，确保集群初始化脚本或库设置中只指定了单一套正确的 Spark NLP 版本，避免在驱动器（Driver）和执行器（Executor）上加载了不同的版本配置。