← 文章 / AI技术
freeCodeCamp 4天前 · 2026-11-18 16:19:05 · 18 阅读

用 Python 构建 NLP 流水线分析治疗进展记录

治疗进展记录是文字形式的会话记录,内容涵盖来访者说了什么、治疗师观察到了什么、讨论的话题,以及下次会话的计划。随着时间推移,这些记录会积累成大量文本。

阅读单条记录能帮助我们理解单次会话。但如果想分析多条记录呢?我们能否借助文本分析,看看语言在不同会话之间是如何变化的?

自然语言处理(NLP)是利用计算机处理人类语言的方法。借助 Python,你可以将文本切分为句子、提取语言特征,并利用模型对情绪和情感进行分类。本教程将使用 spaCy 语言处理流水线 进行文本处理,并使用 Hugging Face Transformers 运行预训练分类模型。

你将构建一个小型 NLP 流水线,用于处理虚构的治疗记录。具体步骤包括:使用 spaCy 处理文本,利用两个现成的 Hugging Face 模型对情绪和情感进行分类,用 pandas 按会话组织结果,以及用 Matplotlib 生成图表。

完整的代码可以在这个 GitHub 仓库 中找到。

我们的目的并非判断治疗是否有效。目标是学习如何把书面文本转化为可审阅、可质疑、可图表化的数据。

完成本教程后,你将拥有一个实用的 Python 项目,使用 spaCy、Hugging Face Transformers、pandas 和 Matplotlib,在虚构的治疗记录中探索情绪、情感和语言模式。

注意:本教程仅用于学习,使用的是虚构文本。这些模型未经过临床使用测试。它们无法判断治疗是否有效、无法识别治疗师与来访者关系中的问题,也不能替代受过专业培训的人员。

目录

  • 用 spaCy 预处理记录
  • 用 DistilBERT 做情感分析
  • 用 DistilRoBERTa 分类情绪
  • 探索语言特征
  • 对比多次咨询的结果
  • 可视化输出结果
  • 串联整个 Pipeline
  • 测试项目
  • 局限性与伦理考量
  • 总结与延伸学习
  • 参考资料
  • NLP 能告诉我们什么、不能告诉我们什么

    自然语言处理(NLP)是人工智能的一个分支,让计算机能够处理人类语言。常见的 NLP 任务包括分词和分句、识别语法、提取人名地名,以及分类情感和情绪。

    每个任务的功能各不相同。Tokenization 把文本切分成更小的单元(比如单词);词性标注判断一个词在句子中的作用(名词还是动词);词形还原把单词映射到它的原形;命名实体识别则提取人名、机构、地点等信息。这些都是 spaCy 处理管道中可用的组件。情感分析根据模型学到的样本,判断文本听起来是正面还是负面;情绪分类则输出模型在训练中学到的各类情绪的得分。

    这些结果并不能告诉我们一个人真实的感受。咨询记录里可能包含咨询师自己的观察、来访者的原话,或者咨询师对来访者所述内容的转述。模型未必知道某句话是谁说的,也理解不了完整的情境。所以在本教程中,我们讨论的是模型预测和语言模式,而不是一个人的情绪或治疗进展。

    我们要构建什么

    本项目将分析一组虚构的咨询记录,并生成四类结果:

    • 对每句话进行情感预测
    • 对每句话进行情绪预测,并计算平均分
    • 提取简单的语言特征,如特定代词的数量,以及“也许”或“我认为”等短语
    • 生成时间轴和仪表盘,用于对比不同咨询会话的结果

    工作流程如下:

    图 1 — 流程图(pipeline-miro.svg)  一个五阶段的 NLP 流水线流程图。阶段 01(输入)接收经过验证的 CSV 格式虚构咨询记录,包含 client_id、session 和 note 字段。阶段 02(预处理)使用配置了空白流水线和分句器的 spaCy 来将文本切分为句子,统计词数,并计算语言比率。随后流程并行分为两个分支:阶段 03A(情感)使用 DistilBERT SST-2 生成正向和负向得分;阶段 03B(情绪)使用 DistilRoBERTa 生成七种情绪的得分,并采用分块加权平均聚合方法。在 03B 下方的独立卡片中列出了七种情绪类别:愤怒、厌恶、恐惧、快乐、中立、悲伤和惊讶。这两个并行分支汇合到阶段 04(探索),输出 CSV 表格、Matplotlib 图表、便携式 HTML 报告和运行清单。一条从阶段 02 延伸出的虚线将五项语言特征(词数、句数、平均句长、词汇多样性、第一人称比率)引入底部条带,并通过客户端和会话键连接到最终输出。

    图 1. NLP 工作流程的高层视图。该图还展示了可能的扩展功能,例如 CSV 和 HTML 报告,但这些功能并非在本教程的每个步骤中都会实现。

    我们将代码分散在不同的文件中,使每个部分只承担一个明确的任务。本项目不会计算关系破裂得分,也不会标记临床结果。

    工具和模型

    Python

    Python 将连接项目的每个部分。它还有许多用于处理数据和语言的库。

    spaCy 是一个用于文本处理的 Python 库。它的 处理管道 能对文本分词、标注词性、还原词的原形,并识别人名、地名等实体。我们将使用它的小型英文模型 en_core_web_sm。该模型针对通用英文文本训练,并非专门面向治疗记录。

    Hugging Face Transformers

    我们将使用两个预训练的分类模型:

    第一个模型是 distilbert/distilbert-base-uncased-finetuned-sst-2-english,用于将文本分类为正面或负面。其 模型卡 显示,这是一个在斯坦福情感树库(SST-2,一个通用英文句子数据集)上微调的 DistilBERT 检查点。DistilBERT 本身出自论文 “DistilBERT, a distilled version of BERT: Smaller, faster, cheaper and lighter”。无论是该检查点还是原始论文,都没有证明这个模型适用于治疗记录。

    第二个模型是 j-hartmann/emotion-english-distilroberta-base,可预测七种情绪类别:愤怒、厌恶、恐惧、喜悦、中性、悲伤和惊讶。根据 Jochen Hartmann 的模型卡,它是在六个数据集(包括社交媒体帖子、学生自我报告和对话)组成的均衡数据上训练的,尚未针对治疗进展记录的分析做过验证。

    这些模型能帮助我们理解文本分类的原理。但由于它们是在通用文本上训练的,不能想当然地认为它们在治疗记录上也能表现良好。

    pandas 和 Matplotlib

    pandas 帮我们把结果整理成名为 DataFrame 的表格,Matplotlib 则帮我们把结果绘制成图表。

    pytest

    搭建 Python 项目

    新建一个项目文件夹,然后进入该目录:

    mkdir therapy_notes_nlp
    cd therapy_notes_nlp
    mkdir data src tests images
    

    项目文件夹和文件结构应如下所示:

    therapy_notes_nlp/
    ├── data/
    │   └── synthetic_notes.json
    ├── images/
    ├── src/
    │   ├── __init__.py
    │   ├── preprocessor.py
    │   ├── sentiment.py
    │   ├── emotions.py
    │   ├── tracker.py
    │   └── visualizer.py
    ├── tests/
    │   ├── conftest.py
    │   ├── test_analyzer.py
    │   ├── test_emotions.py
    │   ├── test_preprocessor.py
    │   ├── test_sentiment.py
    │   └── test_tracker.py
    ├── analyzer.py
    ├── main.py
    ├── pytest.ini
    └── requirements.txt
    

    创建虚拟环境并激活它。虚拟环境可将当前项目的 Python 包与你其他项目使用的包隔离开来:

    python -m venv .venv
    
    # Windows
    .venv\Scripts\activate
    
    # macOS 或 Linux
    source .venv/bin/activate
    

    将以下包添加到 requirements.txt:

    spacy>=3.8,<4.0
    transformers>=4.45,<6.0
    torch>=2.2
    pandas>=2.2,<3.0
    matplotlib>=3.8,<4.0
    pytest>=8.0,<10.0
    

    安装这些包,并下载 spaCy 的英语语言模型:

    pip install -r requirements.txt
    python -m spacy download en_core_web_sm
    

    首次运行项目时,Hugging Face 会下载模型文件。你可以在 CPU 上运行模型,但速度可能比在 GPU 上更慢。

    创建合成数据集

    治疗笔记可能包含隐私信息。为保护个人隐私,本教程将全程使用虚构的示例数据。这也意味着任何人都无需接触真实的患者记录即可跟做此项目。

    本教程请始终使用虚构数据。除非你拥有相应的授权和保护措施,并确认遵守了你所在地区的法律法规,否则不要用真实的治疗笔记替代。

    spaCy 有时能在文本中识别出人名等细节,但也可能漏掉。删掉人名并不等于治疗记录就已匿名。本教程请只使用虚构示例,任何真实的研究项目都需要相应的审批和隐私保护措施。

    如果还没创建,请在 data 文件夹中新建一个 synthetic_notes.json 文件:

    [
      {
        "session": 1,
        "client_id": "SYNTHETIC_001",
        "note": "虚构来访者描述了自己被工作压力压得喘不过气,说最近睡眠困难,不知从何入手。"
      },
      {
        "session": 2,
        "client_id": "SYNTHETIC_001",
        "note": "虚构来访者谈到尝试了新的晚间作息,提到一个有帮助的时刻,同时也表达了持续的担忧。"
      },
      {
        "session": 3,
        "client_id": "SYNTHETIC_001",
        "note": "虚构来访者报告这一周压力很大,感到沮丧,但也找到了一个自己应对方式有所不同的情况。"
      },
      {
        "session": 4,
        "client_id": "SYNTHETIC_001",
        "note": "虚构来访者描述对一次工作谈话感到更有希望,但仍担心能否维持这些改变。"
      },
      {
        "session": 5,
        "client_id": "SYNTHETIC_001",
        "note": "虚构来访者质疑当前方法是否有效,说原本预期进度会不一样,希望就此进行讨论。"
      },
      {
        "session": 6,
        "client_id": "SYNTHETIC_001",
        "note": "虚构来访者与治疗师讨论了此前提出的疑虑。来访者感到被倾听,但也指出仍有一些问题没有解决。"
      },
      {
        "session": 7,
        "client_id": "SYNTHETIC_001",
        "note": "虚构来访者回顾了在一次艰难对话中使用应对策略的经历,既感到释然,也残留一些紧张。"
      },
      {
        "session": 8,
        "client_id": "SYNTHETIC_001",
        "note": "虚构来访者回顾了前几次会谈的话题,描述了自己注意到的变化,并指出仍想继续应对的挑战。"
      }
    ]
    

    每条记录包含会谈次数、一个虚构的来访者 ID 和一段笔记。示例中既有积极的体验,也有困难的经历。我们写这些内容时并没有刻意引导模型给出特定答案,而是让模型实际运行,然后检验其输出结果。

    使用 spaCy 预处理笔记

    在对文本进行分类之前,我们使用 spaCy 将每条笔记拆分为句子,并收集一些关于单词的基本信息。

    在 src/preprocessor.py 中:

    from __future__ import annotations
    from typing import Any
    import spacy
    
    MODEL_NAME = "en_core_web_sm"
    
    def load_nlp(model_name: str = MODEL_NAME):
        return spacy.load(model_name)
    
    _nlp = None
    
    def get_nlp():
        global _nlp
        if _nlp is None:
            _nlp = load_nlp()
        return _nlp
    
    def preprocess_note(text: str, nlp=None) -> dict[str, Any]:
        if not isinstance(text, str):
            raise TypeError("text must be a string")
        if not text.strip():
            return {
                "tokens": [], "lemmas": [], "sentences": [],
                "pos_tags": [], "entities": [],
                "token_count": 0, "sentence_count": 0
            }
    
        doc = (nlp or get_nlp())(text)
        tokens = [t.text.lower() for t in doc if not t.is_punct and not t.is_space]
        lemmas = [
            t.lemma_.lower() for t in doc
            if not t.is_stop and not t.is_punct and not t.is_space and t.is_alpha
        ]
        sentences = [s.text.strip() for s in doc.sents if s.text.strip()]
        pos_tags = [
            {"text": t.text, "pos": t.pos_, "tag": t.tag_}
            for t in doc if not t.is_punct and not t.is_space
        ]
        entities = [{"text": e.text, "label": e.label_} for e in doc.ents]
    
        return {
            "tokens": tokens,
            "lemmas": lemmas,
            "sentences": sentences,
            "pos_tags": pos_tags,
            "entities": entities,
            "token_count": len(tokens),
            "sentence_count": len(sentences)
        }
    

    _nlp = None / get_nlp() 这种模式值得留意。加载 spaCy 模型需要一两秒,不希望每次调用函数都承担这个开销。将 _nlp 设为模块级变量后,模型只加载一次,之后每次调用都复用。代码中 (nlp or get_nlp())(text) 这一行初看可能有些奇怪,但意思很简单:使用传入的模型,否则回退到默认模型。这也让后续的测试更简单,因为可以传入一个轻量的模拟模型代替真实模型。

    有一点需要注意:我们传给分类器的是原始句子,而非清洗后的 token 或词元。这是有意为之。像 "not" 这样的词会改变句子的意思,如果在分类前剔除它们,可能会悄悄改变模型看到的内容。

    entities 字段存放 spaCy 识别出的人名、地名等命名实体。它不会删除或匿名化个人信息。

    用 DistilBERT 做情感分析

    情感分析是根据模型学到的样本,判断文本偏正面还是偏负面。我们选用的 DistilBERT 模型还在 SST-2(一个通用英文句子数据集)上做了进一步训练,会为每个句子输出正面和负面两个分数。

    在 src/sentiment.py 中:

    MODEL_ID = "distilbert/distilbert-base-uncased-finetuned-sst-2-english"
    _pipeline = None
    
    def get_pipeline():
        global _pipeline
        if _pipeline is None:
            from transformers import pipeline
            _pipeline = pipeline(
                "text-classification", model=MODEL_ID, top_k=None
            )
        return _pipeline
    
    def _normalise_prediction(prediction):
        if isinstance(prediction, dict):
            return [prediction]
        if prediction and isinstance(prediction[0], list):
            return prediction[0]
        return prediction
    
    def analyze_sentiment(sentences: list[str], classifier=None) -> dict:
        clean = [s.strip() for s in sentences if isinstance(s, str) and s.strip()]
        if not clean:
            return {
                "sentence_results": [], "aggregate_score": None,
                "aggregate_label": None, "positive_ratio": 0.0,
                "negative_ratio": 0.0
            }
    
        model = classifier or get_pipeline()
        predictions = model(clean, truncation=True, batch_size=8)
        results = []
    
        for sentence, prediction in zip(clean, predictions):
            scores = _normalise_prediction(prediction)
            by_label = {
                item["label"].upper(): float(item["score"])
                for item in scores
            }
            positive = by_label.get("POSITIVE", 0.0)
            negative = by_label.get("NEGATIVE", 0.0)
            signed_score = positive - negative
            label = (
                "POSITIVE" if signed_score > 0
                else "NEGATIVE" if signed_score < 0
                else "BALANCED"
            )
            results.append({
                "sentence": sentence,
                "label": label,
                "positive_score": positive,
                "negative_score": negative,
                "signed_score": round(signed_score, 4)
            })
    
        values = [item["signed_score"] for item in results]
        aggregate = sum(values) / len(values)
        return {
            "sentence_results": results,
            "aggregate_score": round(aggregate, 4),
            "aggregate_label": (
                "POSITIVE" if aggregate > 0
                else "NEGATIVE" if aggregate < 0
                else "BALANCED"
            ),
            "positive_ratio": round(
                sum(item["label"] == "POSITIVE" for item in results) / len(results), 3
            ),
            "negative_ratio": round(
                sum(item["label"] == "NEGATIVE" for item in results) / len(results), 3
            )
        }
    

    get_pipeline() 采用了和 get_nlp() 相同的懒加载模式:模型只加载一次,后续调用都复用它。设置 top_k=None 是让 Hugging Face pipeline 返回所有标签的分数,而不只是得分最高的那个;否则我们只能拿到获胜标签,无法对比两者的分数。truncation=True 会截断超过 512 个 token 的输入,这是模型能处理的上限。batch_size=8 则是一次最多把八句话一起送入模型,比逐句处理更快。

    之所以要有 _normalise_prediction(),是因为 pipeline 返回结果的形状会随版本和配置而变化。它把各种形状统一转换成 {"label": ..., "score": ...} 字典组成的列表,这样函数后续部分处理的数据格式就始终一致了。

    对每句话来说,by_label 是一个用推导式构建的字典,把大写标签映射到对应分数。signed_score 用正向分数减去负向分数,得到一个介于 -1 和 +1 之间的值。最后,函数对所有 signed score 求平均值,为该次会谈生成一个 aggregate_score。

    这个指数只是我们根据模型分数计算出的一个汇总指标,既不是医学认证的测量工具,也不代表康复程度或幸福程度。分数接近零也可能意味着正负结果相互抵消。

    用 DistilRoBERTa 分类情绪

    情感分析(sentiment)和情绪分类(emotion)并不是一回事。情感分析只给出宽泛的正负判断,情绪分类则关注喜悦、悲伤、愤怒、恐惧等具体类别。

    在 src/emotions.py 中:

    MODEL_ID = "j-hartmann/emotion-english-distilroberta-base"
    _pipeline = None
    
    def get_pipeline():
        global _pipeline
        if _pipeline is None:
            from transformers import pipeline
            _pipeline = pipeline(
                "text-classification", model=MODEL_ID, top_k=None
            )
        return _pipeline
    
    def _normalise_prediction(prediction):
        if isinstance(prediction, dict):
            return [prediction]
        if prediction and isinstance(prediction[0], list):
            return prediction[0]
        return prediction
    
    def detect_emotions(sentences: list[str], classifier=None) -> dict:
        clean = [s.strip() for s in sentences if isinstance(s, str) and s.strip()]
        if not clean:
            return {
                "per_sentence": [], "emotion_distribution": {},
                "session_dominant_emotion": None
            }
    
        model = classifier or get_pipeline()
        predictions = model(clean, truncation=True, batch_size=8)
        per_sentence = []
        totals = {}
    
        for sentence, prediction in zip(clean, predictions):
            scores = _normalise_prediction(prediction)
            score_map = {
                item["label"].lower(): float(item["score"])
                for item in scores
            }
            for label, score in score_map.items():
                totals[label] = totals.get(label, 0.0) + score
            dominant = max(score_map, key=score_map.get)
            per_sentence.append({
                "sentence": sentence,
                "dominant_emotion": dominant,
                "scores": score_map
            })
    
        distribution = {
            label: round(score / len(clean), 4)
            for label, score in totals.items()
        }
        dominant_session = max(distribution, key=distribution.get)
        return {
            "per_sentence": per_sentence,
            "emotion_distribution": distribution,
            "session_dominant_emotion": dominant_session
        }
    

    totals 字典用于累积各句子的得分。循环处理每个句子时,会将每种情绪标签的得分累加到总和中。使用 totals.get(label, 0.0) 可以安全处理标签首次出现的情况,将其初始值设为零,避免键错误。

    max(score_map, key=score_map.get) 用于找出当前句子 score_map 中得分最高的标签。key 参数指示 max() 函数比较字典中的值,而不是键本身。

    处理完所有句子后,distribution 会将累计总分除以句子数量,得出整个会谈中每种情绪的平均得分。max(distribution, key=distribution.get) 用同样的方式找出会谈层面的主导情绪。

    这些结果只是模型的预测,并不能确认任何人的真实感受。模型是在通用英文文本上训练的,而治疗记录的写作目的不同,用语习惯也可能不同,不能假设模型在这些文本上能可靠工作。

    探索语言特征

    我们还可以统计一些简单的语言特征。例如,统计第一人称代词出现的频率,并查找 "maybe"、"perhaps"、"I guess" 这类短语。这些是典型的模糊措辞(hedging phrases),人们常常在不确定或谨慎表达时使用。

    将下面的函数添加到 src/preprocessor.py:

    def extract_linguistic_features(text: str) -> dict:
        doc = get_nlp()(text)
        first_person = {
            "i", "me", "my", "mine", "myself", "we", "us",
            "our", "ours", "ourselves"
        }
        third_person = {
            "he", "him", "his", "himself", "she", "her", "hers",
            "herself", "they", "them", "their", "theirs",
            "themselves", "it", "its", "itself"
        }
        second_person = {"you", "your", "yours", "yourself", "yourselves"}
    
        pronouns = [token.text.lower() for token in doc if token.pos_ == "PRON"]
        first = sum(word in first_person for word in pronouns)
        third = sum(word in third_person for word in pronouns)
        second = sum(word in second_person for word in pronouns)
        total = first + third + second
    
        hedging_phrases = (
            "maybe", "perhaps", "possibly", "i guess", "not sure",
            "sort of", "kind of", "i think", "might"
        )
        lower = text.lower()
        hedging_count = sum(lower.count(phrase) for phrase in hedging_phrases)
    
        return {
            "first_person_count": first,
            "third_person_count": third,
            "second_person_count": second,
            "pronoun_count": total,
            "first_person_ratio": round(first / total, 3) if total else 0.0,
            "hedging_phrase_count": hedging_count
        }
    

    token.pos_ == "PRON" 通过词性标签筛选 token。spaCy 将此类标签分配给它识别出的代词。first_person、third_person 和 second_person 这三个集合分别定义了属于各组的小写单词。sum() 内部的生成器表达式检查每个代词 token 的文本是否属于相应集合,并统计匹配数量。

    first_person_ratio 用第一人称代词数量除以代词总数。if total else 0.0 这一判断防止了文本中不含代词时出现除零错误。

    对于保留性措辞,先通过 text.lower() 将整个笔记转为小写再进行搜索,这样 "Maybe" 和 "maybe" 被视为相同。lower.count(phrase) 返回该短语作为子串出现的次数。每个短语的结果都会累加到 hedging_count 中。

    这些数据仅仅是计数。它们无法解释为何使用某个特定词语或短语,其含义取决于上下文及笔记作者。要判断这些特征是否有用,需要将其与精心标注的示例进行对比,但这超出了本教程的范围。

    对比各次会谈的结果

    每次会谈都会生成一组结果。我们将使用 pandas 将这些结果放入表格中,每次会谈占一行,便于纵向对比随时间变化的结果。

    在 src/tracker.py 中:

    import pandas as pd
    
    def build_session_timeline(session_results: list[dict]) -> pd.DataFrame:
        rows = []
        for result in session_results:
            sentiment = result["sentiment"]
            emotions = result["emotions"]
            linguistic = result["linguistic_features"]
            rows.append({
                "session": result["session"],
                "sentiment_index": sentiment["aggregate_score"],
                "sentiment_label": sentiment["aggregate_label"],
                "dominant_emotion": emotions["session_dominant_emotion"],
                "first_person_ratio": linguistic["first_person_ratio"],
                "hedging_phrase_count": linguistic["hedging_phrase_count"],
                "sentence_count": result["sentence_count"]
            })
    
        columns = [
            "session", "sentiment_index", "sentiment_label",
            "dominant_emotion", "first_person_ratio",
            "hedging_phrase_count", "sentence_count"
        ]
        if not rows:
            return pd.DataFrame(columns=columns)
        return pd.DataFrame(rows).sort_values("session").reset_index(drop=True)
    
    def describe_sentiment_shift(df: pd.DataFrame) -> dict:
        if df.empty:
            return {
                "session_count": 0,
                "first_half_mean": None,
                "second_half_mean": None,
                "difference": None,
                "description": "没有可对比的咨询记录"
            }
    
        midpoint = max(1, len(df) // 2)
        first = df.iloc[:midpoint]["sentiment_index"].dropna()
        second = df.iloc[midpoint:]["sentiment_index"].dropna()
        first_mean = float(first.mean()) if not first.empty else None
        second_mean = float(second.mean()) if not second.empty else None
        difference = (
            second_mean - first_mean
            if first_mean is not None and second_mean is not None
            else None
        )
    
        if difference is None:
            description = "非缺失分数不足,无法对比前后两期"
        elif difference > 0.05:
            description = "后半期的模型情感指数平均值更高"
        elif difference < -0.05:
            description = "后半期的模型情感指数平均值更低"
        else:
            description = "前后两期的平均值差异不大"
    
        return {
            "session_count": len(df),
            "first_half_mean": first_mean,
            "second_half_mean": second_mean,
            "difference": round(difference, 4) if difference is not None else None,
            "description": description
        }
    

    build_session_timeline() 遍历每个会话的结果,从嵌套字典中提取所需字段,并将扁平化的字典作为一行添加。随后,pd.DataFrame(rows) 将这组行数据转换为表格。.sort_values("session") 按会话编号对行进行排序,而 .reset_index(drop=True) 则将索引重置为从零开始的整洁序列。

    在 describe_sentiment_shift() 中,df.iloc[:midpoint] 按位置选取前半部分的行。在计算均值之前,先使用 .dropna() 移除 sentiment_index 缺失的行,这样可以避免单个缺失值导致整体平均值为 NaN。设定 0.05 的阈值是为了防止描述将微小的数值差异解读为有意义的变化。

    该描述仅针对模型的情绪指数。我们刻意避免使用“显著改善”或“临床恶化”等标签,因为模型分数变化并不能证明患者的心理健康或治疗进程发生了实际改变。

    可视化输出结果

    与单纯的表格相比,图表能让结果更直观易懂。我们将创建四个图表:情绪指数、每个会话最可能的情绪、第一人称代词的占比,以及模糊限制语的数量。

    在 src/visualizer.py 中:

    import matplotlib.pyplot as plt
    import pandas as pd
    
    def plot_dashboard(
        df: pd.DataFrame,
        output_path: str = "images/session_dashboard.png"
    ):
        if df.empty:
            raise ValueError("Cannot plot an empty session timeline")
    
        fig, axes = plt.subplots(2, 2, figsize=(12, 8))
        sessions = df["session"]
    
        axes[0, 0].plot(sessions, df["sentiment_index"], marker="o")
        axes[0, 0].axhline(0, linestyle="--", linewidth=1)
        axes[0, 0].set(
            title="Model sentiment index by session",
            xlabel="Session",
            ylabel="Positive score minus negative score"
        )
    
        emotion_codes = {
            name: i for i, name in enumerate(
                sorted(df["dominant_emotion"].dropna().unique())
            )
        }
        emotion_values = [
            emotion_codes.get(value, -1)
            for value in df["dominant_emotion"]
        ]
        axes[0, 1].scatter(sessions, emotion_values)
        axes[0, 1].set(
            title="Dominant predicted emotion",
            xlabel="Session",
            ylabel="Emotion category"
        )
        axes[0, 1].set_yticks(
            list(emotion_codes.values()), list(emotion_codes.keys())
        )
    
        axes[1, 0].plot(sessions, df["first_person_ratio"], marker="o")
        axes[1, 0].set(
            title="First-person pronoun share",
            xlabel="Session",
            ylabel="Share of counted pronouns",
            ylim=(0, 1)
        )
    
        axes[1, 1].bar(sessions, df["hedging_phrase_count"])
        axes[1, 1].set(
            title="Selected hedging phrases",
            xlabel="Session",
            ylabel="Phrase count"
        )
    
        fig.suptitle("Exploratory text-analysis outputs (synthetic data)")
        fig.tight_layout()
        fig.savefig(output_path, dpi=160, bbox_inches="tight")
        plt.close(fig)
        return output_path
    

    plt.subplots(2, 2, figsize=(12, 8)) 会创建一个包含 2×2 子图网格的画布,返回画布对象 fig 和一个二维数组 axes,通过 axes[row, col] 即可访问每张图表。

    情感图表通过 axes[0, 0].axhline(0) 在零点处画一条水平参考线,这样一眼就能看出哪些疗程的指数是净正值、哪些是净负值。

    情感图表需要额外处理一步,因为 Matplotlib 的散点图要求输入数值而非字符串。emotion_codes 是一个字典,它利用 enumerate 将每个独特的情感标签映射为整数。emotion_values 则将主导情感列转换为这些整数以便绘图。set_yticks() 随后在 y 轴上恢复原始的标签名称,使图表显示文字而非数字。

    fig.tight_layout() 自动调整子图之间的间距,防止标题和标签重叠。fig.savefig() 将完成的图表写入文件,plt.close(fig) 释放图表占用的内存。

    [图 2: figure-2.png]

    图 2 — Matplotlib 输出 (demo-overview.png)  一个三面板图表,展示了两个虚拟心理咨询客户各自五个疗程的 NLP 模型输出。顶部面板是情绪(积极得分)随疗程变化的折线图;虚构客户 A 整体积极性较高且随疗程波动,而虚构客户 B 则呈现较低趋势。中间面板是每个客户在七个类别上平均情感得分的热力图。虚构客户 A 在喜悦(0.39)和恐惧(0.38)上得分最高,厌恶、悲伤和惊讶接近零。虚构客户 B 在悲伤(0.39)上得分最高,其次是恐惧(0.23)和愤怒(0.20),厌恶和惊讶接近零。底部面板是每个疗程平均句子长度的柱状图,展示了客户内部和之间的变化。

    图 2. 来自虚构疗程的仪表盘示例。得分和语言计数均为模型输出和文本特征,并非咨询进展的度量。

    每张图表展示不同的结果。情绪图表展示了我们从模型得分中计算出的指数。情感图表展示了每个疗程中得分最高的类别。另外两张图表展示了直接从文本中提取的计数或比例。

    这个仪表盘并非某人咨询进展的报告。它仅展示由我们的代码和所选模型生成的结果。

    连接管道

    接下来,我们将使用 Python 类连接项目的不同部分。这样在分析单条或多条笔记时,我们有了一个统一的入口。

    在 analyzer.py 中:

    from src.preprocessor import preprocess_note, extract_linguistic_features
    from src.sentiment import analyze_sentiment
    from src.emotions import detect_emotions
    from src.tracker import build_session_timeline, describe_sentiment_shift
    
    class TherapyNoteAnalyzer:
        def analyze_session(self, note_data: dict) -> dict:
            required = {"session", "client_id", "note"}
            missing = required - note_data.keys()
            if missing:
                raise ValueError(f"Missing required fields: {sorted(missing)}")
    
            processed = preprocess_note(note_data["note"])
            sentiment = analyze_sentiment(processed["sentences"])
            emotions = detect_emotions(processed["sentences"])
            linguistic = extract_linguistic_features(note_data["note"])
    
            return {
                "session": note_data["session"],
                "client_id": note_data["client_id"],
                "sentence_count": processed["sentence_count"],
                "sentiment": sentiment,
                "emotions": emotions,
                "linguistic_features": linguistic,
                "entity_candidates": processed["entities"]
            }
    
        def analyze_all(self, notes: list[dict]) -> dict:
            if not notes:
                timeline = build_session_timeline([])
                return {
                    "client_id": None,
                    "session_results": [],
                    "timeline": timeline,
                    "sentiment_comparison": describe_sentiment_shift(timeline)
                }
    
            client_ids = {item.get("client_id") for item in notes}
            if len(client_ids) != 1:
                raise ValueError(
                    "This example expects notes for one synthetic client at a time"
                )
    
            results = [self.analyze_session(item) for item in notes]
            timeline = build_session_timeline(results)
            return {
                "client_id": next(iter(client_ids)),
                "session_results": results,
                "timeline": timeline,
                "sentiment_comparison": describe_sentiment_shift(timeline)
            }
    

    最后,在 main.py 中:

    import json
    from pathlib import Path
    from analyzer import TherapyNoteAnalyzer
    from src.visualizer import plot_dashboard
    
    def main():
        with Path("data/synthetic_notes.json").open(encoding="utf-8") as file:
            notes = json.load(file)
    
        results = TherapyNoteAnalyzer().analyze_all(notes)
        print(results["timeline"].to_string(index=False))
        print("\nDescriptive comparison:", results["sentiment_comparison"])
    
        output = plot_dashboard(results["timeline"])
        print(f"\nSaved dashboard to {output}")
        print("Reminder: these model outputs are exploratory, not clinical assessments.")
    
    if __name__ == "__main__":
        main()
    

    在项目根目录运行该工程:

    python main.py
    

    首次运行脚本时,它会下载两个 Hugging Face 模型。随后,脚本会输出会话结果表格,并在 images 文件夹中保存仪表盘图像。

    由于模型版本及代码执行方式不同,结果可能存在差异。务必核对你自己运行得到的结果。表述时应说明“模型预测了什么”,而不是断言某次会话“显示”或“揭示”了什么。模型预测并不等同于事实证据。

    测试该项目

    测试有助于检查函数在常规输入和异常情况(如空文本)下的表现。通过测试并不证明模型在临床环境中是准确或有用的。

    对于情感与情绪测试,我们将使用返回预设结果的虚拟分类器。这样可以加快测试速度,也无需下载模型文件。

    一个简化的情感测试示例如下:

    from src.sentiment import analyze_sentiment
    
    class FakeSentiment:
        def __call__(self, texts, **kwargs):
            return [
                [
                    {"label": "POSITIVE", "score": 0.8},
                    {"label": "NEGATIVE", "score": 0.2}
                ],
                [
                    {"label": "POSITIVE", "score": 0.1},
                    {"label": "NEGATIVE", "score": 0.9}
                ]
            ][:len(texts)]
    
    def test_sentiment_score_is_positive_minus_negative():
        result = analyze_sentiment(
            ["Good sentence.", "Bad sentence."],
            classifier=FakeSentiment()
        )
        assert result["sentence_results"][0]["signed_score"] == 0.6
        assert result["sentence_results"][1]["signed_score"] == -0.8
    

    FakeSentiment 能直接替代真实模型,靠的是它定义了 __call__。当 Python 遇到 model(clean, ...) 时,实际调用的是 model.__call__(clean, ...),所以任何带这个方法的对象都能像函数一样被调用。FakeSentiment.__call__ 无论输入什么文本都返回固定的分数列表,这意味着测试可以只验证计算逻辑,而不用下载模型。

    [:len(texts)] 把返回值切片成和输入句子数量一致。这样可以避免假分类器返回的结果比输入多,否则 analyze_sentiment 里的 zip() 会出现意外行为。

    给 analyze_sentiment 传入 classifier=FakeSentiment(),就能在这一步覆盖掉 get_pipeline()。这种模式叫依赖注入:函数从外部接收依赖,而不是在内部自己创建,这样函数更容易测试和复用。

    完整项目包含针对以下场景的测试:空输入、句子切分、词处理、情感分数计算、情绪分数汇总、会话排序、空时间线,以及必填输入字段是否齐全。

    在项目根目录运行测试套件:

    python -m pytest -q
    

    项目压缩包里共有 15 个测试,检查时全部通过。有些测试使用虚构的模型结果,有些则用一个小型 spaCy 配置来验证选定的文本处理步骤。这些测试不衡量模型准确率,不确认情绪标签是否正确,也不反映模型在真实治疗记录上的表现。

    局限性与伦理考量

    由于这个项目涉及治疗相关文本,我们必须认真考虑隐私问题、模型的局限性,以及语言模式与专业临床评估之间的差距。

    通用领域模型不是临床模型

    DistilBERT 模型是在 SST-2 数据集上训练的,而非治疗记录。DistilRoBERTa 模型则基于混合的通用英语文本进行训练。除非使用合适的数据集和明确的标签进行独立测试,否则我们无法确定这些模型在临床记录中的实际表现。此外,这些模型可能难以妥善处理正式书面语、非母语英语使用者以及不同文化中表达痛苦的方式,因为其训练数据并未专为覆盖这些场景而设计。

    情感不等于治疗进展

    积极的语句并不能证明客户正在好转,消极的语句也不代表治疗失败。记录内容可能包含治疗师的观点、客户本人的原话、艰难的事件,或是这些内容的混合体。模型可能无法准确区分这些差异。

    语言特征不等于心理诊断

    代词计数和模糊限制语是文本中简单的特征。这些计数的变化并不能证明客户正在退缩、回避某个话题、失去信任,或与治疗师关系出现问题。由于相关评分规则和警报级别未经过测试或获得临床使用的批准,我们已在该项目早期版本中移除了破裂分数(rupture score)。

    隐私要求因司法管辖区而异

    在美国,HIPAA 适用于特定的医疗组织及其商业合作伙伴。其他国家也有各自的数据保护和医疗隐私法律。在使用真实记录之前,组织必须核查适用的法律、自身政策、数据使用的法律依据、所需的同意书、涉及的服务商和供应商、安全措施以及数据保留期限。本教程不能替代此类审查。即使 HIPAA 不适用于你所在的地区,也不意味着处理真实的治疗记录是安全或合乎伦理的。

    人工监督与透明度

    本项目并非用于临床决策,也不应作为决策依据。任何拟用于实际医疗工作的 NLP 工具都必须针对特定环境进行测试。此外,还需进行隐私和偏差审查,提供清晰的文档,并接受合格专业人士的监督。相关规则要求向信息被使用的个人告知此事。

    结论与进阶学习

    在这个项目中,我们用 spaCy、Hugging Face Transformers、pandas 和 Matplotlib 搭建了一套 NLP 工作流。借助虚构的治疗记录,我们演示了如何分句、做情感和情绪分类、统计语言特征、对比多次会话、绘制图表以及测试代码。

    NLP 可以把大量文本转化为可整理、可探索的数据。但结果是有局限性的——尤其是在敏感文本上使用一个从未针对该类文本训练或测试过的通用模型时。

    如果你想在这个项目的基础上继续深入,这里有几个方向:

    尝试不同的情感分析模型并对比它们的预测结果,观察它们在哪些地方一致、哪些地方有分歧。

    在对模型性能下结论之前,先构建一个人工标注的数据集,并获取相应的伦理审批。

    如果你有正确的标注数据可供对比,可以用 precision、recall、F1-score 和混淆矩阵等指标来评估模型表现。

    探索 scispaCy 等临床 NLP 工具。不过要记住,即使是专为医学文本设计的工具,也需要针对你的具体任务做测试。

    构建一个 Streamlit 应用,让人们只用虚构的示例来体验这个项目。

    想了解更多,可以阅读 spaCy 文档、DistilBERT 情感模型卡和 DistilRoBERTa 情绪模型卡。你也可以阅读 Edward S. Bordin 1979 年的论文《The Generalizability of the Psychoanalytic Concept of the Working Alliance》,了解治疗师与来访者之间工作关系的背景知识。

    NLP 能帮助我们研究海量文本,但负责任地使用它,意味着要理解数据、清楚模型的训练目标,并明确它的结果不能告诉我们什么。

    如果你想进一步研究这个项目,可以查看 GitHub 仓库。我把代码和项目结构都放在了那里,你可以了解整体的运作方式。如果你好奇 Python 和 NLP 在医疗、健康科技、临床 NLP 和 AI 等领域的应用,这也是一个不错的起点。这个领域还有很多值得探索的地方,希望这个项目能给你带来一些灵感。

    参考资料

    原始来源: freeCodeCamp

    评论 (0)