Python3.12.3环境中Jupyter导入spaCy遇TypeError问题求助

我需要在Jupyter环境中配置spaCy用于YouTube字幕总结，但在Python3.12.4/3.12.3版本下遇到问题。先尝试了Python3.12.4，后来用conda创建了py3.12.3环境，通过pip install spacy安装了spaCy3.7.6。

环境信息 #

conda环境列表：

base                     /opt/anaconda3
py3.11                *  /opt/anaconda3/envs/py3.11
py3.12.3                 /opt/anaconda3/envs/py3.12.3

操作步骤 #

通过以下命令添加Python内核：

jupyter kernelspec install py3.12.3
python -m ipykernel install --user --name=py3.12.3

命令行中import spacy可正常执行：

(py3.12.3) UID ~ % python           
Python 3.12.3 | packaged by Anaconda, Inc. | (main, May  6 2024, 14:43:12) [Clang 14.0.6 ] on darwin
Type "help", "copyright", "credits" or "license" for more information.
>>> import spacy
>>> quit()
(py3.12.3) UID ~ % pip freeze | grep spacy
spacy==3.7.6
spacy-legacy==3.0.12
spacy-loggers==1.0.5

但在base环境启动的Jupyter中（安装后已重启），执行import spacy出现如下错误：

---------------------------------------------------------------------------
TypeError                                 Traceback (most recent call last)
Cell In[2], line 1
----> 1 import spacy # module will be used  to build NLP model
      2 from spacy.lang.en.stop_words import STOP_WORDS # module will be used  to build NLP model
      3 from string import punctuation

File /opt/anaconda3/lib/python3.12/site-packages/spacy/__init__.py:13
     10 # These are imported as part of the API
     11 from thinc.api import Config, prefer_gpu, require_cpu, require_gpu  # noqa: F401
---> 13 from . import pipeline  # noqa: F401
     14 from . import util
     15 from .about import __version__  # noqa: F401

File /opt/anaconda3/lib/python3.12/site-packages/spacy/pipeline/__init__.py:1
----> 1 from .attributeruler import AttributeRuler
      2 from .dep_parser import DependencyParser
      3 from .edit_tree_lemmatizer import EditTreeLemmatizer

File /opt/anaconda3/lib/python3.12/site-packages/spacy/pipeline/attributeruler.py:8
      6 from .. import util
      7 from ..errors import Errors
---> 8 from ..language import Language
      9 from ..matcher import Matcher
     10 from ..scorer import Scorer

File /opt/anaconda3/lib/python3.12/site-packages/spacy/language.py:43
     41 from .lang.tokenizer_exceptions import BASE_EXCEPTIONS, URL_MATCH
     42 from .lookups import load_lookups
---> 43 from .pipe_analysis import analyze_pipes, print_pipe_analysis, validate_attrs
     44 from .schemas import (
     45     ConfigSchema,
     46     ConfigSchemaInit,
   (...)
     49     validate_init_settings,
     50 )
     51 from .scorer import Scorer

File /opt/anaconda3/lib/python3.12/site-packages/spacy/pipe_analysis.py:6
      3 from wasabi import msg
      5 from .errors import Errors
---> 6 from .tokens import Doc, Span, Token
      7 from .util import dot_to_dict
      9 if TYPE_CHECKING:
     10     # This lets us add type hints for mypy etc. without causing circular imports

File /opt/anaconda3/lib/python3.12/site-packages/spacy/tokens/__init__.py:1
----> 1 from ._serialize import DocBin
      2 from .doc import Doc
      3 from .morphanalysis import MorphAnalysis

File /opt/anaconda3/lib/python3.12/site-packages/spacy/tokens/_serialize.py:14
     12 from ..errors import Errors
     13 from ..util import SimpleFrozenList, ensure_path
---> 14 from ..vocab import Vocab
     15 from ._dict_proxies import SpanGroups
     16 from .doc import DOCBIN_ALL_ATTRS as ALL_ATTRS

File /opt/anaconda3/lib/python3.12/site-packages/spacy/vocab.pyx:1, in init spacy.vocab()

File /opt/anaconda3/lib/python3.12/site-packages/spacy/tokens/doc.pyx:49, in init spacy.tokens.doc()

File /opt/anaconda3/lib/python3.12/site-packages/spacy/schemas.py:195
    191         obj = converted
    192     return validate(TokenPatternSchema, {"pattern": obj})
---> 195 class TokenPatternString(BaseModel):
    196     REGEX: Optional[Union[StrictStr, "TokenPatternString"]] = Field(None, alias="regex")
    197     IN: Optional[List[StrictStr]] = Field(None, alias="in")

File /opt/anaconda3/lib/python3.12/site-packages/pydantic/v1/main.py:286, in ModelMetaclass.__new__(mcs, name, bases, namespace, **kwargs)
    284 cls.__signature__ = ClassAttribute('__signature__', generate_model_signature(cls.__init__, fields, config))
    285 if resolve_forward_refs:
---> 286     cls.__try_update_forward_refs__()
    288 # preserve `__set_name__` protocol defined in https://peps.python.org/pep-0487
    289 # for attributes not in `new_namespace` (e.g. private attributes)
    290 for name, obj in namespace.items():

File /opt/anaconda3/lib/python3.12/site-packages/pydantic/v1/main.py:808, in BaseModel.__try_update_forward_refs__(cls, **localns)
    802 @classmethod
    803 def __try_update_forward_refs__(cls, **localns: Any) -> None:
    804     """
    805     Same as update_forward_refs but will not raise exception
    806     when forward references are not defined.
    807     """
---> 808     update_model_forward_refs(cls, cls.__fields__.values(), cls.__config__.json_encoders, localns, (NameError,))

File /opt/anaconda3/lib/python3.12/site-packages/pydantic/v1/typing.py:554, in update_model_forward_refs(model, fields, json_encoders, localns, exc_to_suppress)
    552 for f in fields:
    553     try:
---> 554         update_field_forward_refs(f, globalns=globalns, localns=localns)
    555     except exc_to_suppress:
    556         pass

File /opt/anaconda3/lib/python3.12/site-packages/pydantic/v1/typing.py:529, in update_field_forward_refs(field, globalns, localns)
    527 if field.sub_fields:
    528     for sub_f in field.sub_fields:
---> 529         update_field_forward_refs(sub_f, globalns=globalns, localns=localns)
    531 if field.discriminator_key is not None:
    532     field.prepare_discriminated_union_sub_fields()

File /opt/anaconda3/lib/python3.12/site-packages/pydantic/v1/typing.py:520, in update_field_forward_refs(field, globalns, localns)
    518 if field.type_.__class__ == ForwardRef:
    519     prepare = True
---> 520     field.type_ = evaluate_forwardref(field.type_, globalns, localns or None)
    521 if field.outer_type_.__class__ == ForwardRef:
    522     prepare = True

File /opt/anaconda3/lib/python3.12/site-packages/pydantic/v1/typing.py:66, in evaluate_forwardref(type_, globalns, localns)
     63 def evaluate_forwardref(type_: ForwardRef, globalns: Any, localns: Any) -> Any:
     64     # Even though it is the right signature for python 3.9, mypy complains with
     65     # `error: Too many arguments for "_evaluate" of "ForwardRef"` hence the cast...
---> 66     return cast(Any, type_)._evaluate(globalns, localns, set())

TypeError: ForwardRef._evaluate() missing 1 required keyword-only argument: 'recursive_guard'

解决方案 #

原因分析 #

这个错误有两个核心原因：

1. Python 3.12对ForwardRef._evaluate()方法的签名做了改动，新增了recursive_guard参数，而spaCy 3.7.6依赖的旧版本pydantic v1不兼容这个改动。
2. 从报错路径/opt/anaconda3/lib/python3.12/site-packages/可以看出，Jupyter实际调用的是base环境的包，而非你创建的py3.12.3环境的包，内核关联出现问题。

修复步骤 #

1. 重新关联Jupyter内核到目标环境
   先删除错误的内核配置，重新安装：

   # 删除旧内核
   jupyter kernelspec uninstall py3.12.3
   # 激活目标conda环境
   conda activate py3.12.3
   # 确保当前环境安装了ipykernel
   pip install ipykernel
   # 重新注册内核，明确关联当前环境
   python -m ipykernel install --user --name=py3.12.3 --display-name="Python 3.12.3 (spaCy)"
   

2. 升级spaCy到兼容Python 3.12的版本
   spaCy 3.7.6对Python 3.12的支持不完善，升级到3.8.0及以上版本即可解决pydantic兼容问题：

   conda activate py3.12.3
   pip install --upgrade spacy
   

3. 验证修复效果
   启动Jupyter后，选择Python 3.12.3 (spaCy)内核，执行以下代码验证：

   import spacy
   print(spacy.__version__)
   # 输出应为3.8.0及以上版本，且无报错
   

内容的提问来源于stack exchange，提问作者frankr6591