简介：这份资源面向希望快速上手中文任务型对话机器人开发的Python学习者与初级工程师，基于Flask与Rasa框架搭建，可直接替换数据投入使用。压缩包共109个文件，约7.51MB，涵盖7个py源码文件、6个yml配置、13个json数据、35个txt语料及md部署文档、pdf说明、pkl模型、html/css/js前端页面等，从对话策略配置、意图实体识别到Web交互界面均有对应文件，目录结构清晰便于按模块查阅。资源已吸引117人学习下载，适合作为课程设计、毕业项目或对话系统入门练手。读者可获得完整可运行的项目源码、部署文档与全部数据资料，理解Rasa的NLU与Core配置流程、Flask如何承载对话接口，并借助前端页面观察多轮任务型对话效果，为后续定制垂直领域机器人打下基础。
1. 从一份 Flask+rasa 对话机器人源码包说起：它到底能跑出什么
如果你手头正好有一个「中文任务型对话机器人」的需求，比如查天气、订票、问订单状态，又不想从零搭 NLU 管线，那这份基于 Flask+rasa 的源码包值得先拆开看看。它不是那种只丢几个 py 文件的半成品，压缩包里带了部署文档和全部数据资料，连component_2_MitieEntityExtractor.dat这种训练产物、story_graph.dot对话流图、20190618-115023.tar.gz模型归档都在，说明作者是跑通过一轮完整训练才打包的。Flask 负责对外暴露 HTTP 接口和前端页面，rasa 负责意图识别、实体抽取和对话状态管理，两者拼起来就是一个能对话的最小闭环。适合谁？刚接触 flask 开发又想碰对话系统的同学，或者需要快速交一个任务型 bot demo 的从业者。下面我按「先跑起来、再拆结构、最后调优」的顺序，把这份资源里真正能复现的部分讲透。
2. 环境搭建与首次启动：把 Flask 和 rasa 两个服务拉起来
2.1 版本选型：为什么是 Python 3.7 而不是更新版本
这份源码的部署文档明确写了 python3.7 或 3.7 以上，但实际踩过 rasa 的人都清楚，rasa 对 Python 版本和依赖版本极其敏感。rasa 1.x/2.x 时代大量依赖tensorflow、sanitized这类包，Python 3.9 之后很多 wheel 直接没有预编译版本，pip 会尝试源码编译，然后卡在tokenizers或numpy的 C 扩展上。我一般会建议用conda单独开一个 3.7 环境，而不是在系统 Python 上直接装，避免污染全局。
# 创建独立环境，避免和系统 Python 打架 conda create -n flask_rasa python=3.7 conda activate flask_rasa # 升级 pip，老版本 pip 解析依赖容易出错 python -m pip install --upgrade pip # 先装 rasa，再装 Flask，顺序反了可能触发依赖回退 pip install rasa==2.8.1 pip install flask==1.1.2这里rasa==2.8.1只是常见做法，具体版本以部署文档为准。逻辑上先装 rasa 是因为它会锁定numpy、scikit-learn等底层库的版本，Flask 相对独立，后装不容易被降级。参数上python=3.7是硬约束，rasa版本要和源码里的config.yml对齐，否则加载模型时会报InvalidModelError。
2.2 目录结构与两个服务的启动顺序
拿到压缩包后先别急着 IDEA 打开，用命令行tree看一眼结构更清楚。典型布局是app.py（Flask 入口）、actions/（自定义 action）、data/（nlu.md、stories.md）、models/（训练好的模型）、static/和templates/（前端页面）。style.css、chat_interface.css、temporary.css这些就是聊天界面的样式文件，懂你.gif、猪猪.gif是界面里的表情素材。
启动顺序必须是先 rasa 后 Flask，因为 Flask 的/chat接口会去请求 rasa server 的 5005 端口。
# 终端 1：启动 rasa 服务，加载指定模型 rasa run --model models/20190618-115023.tar.gz --enable-api --cors "*" --port 5005 # 终端 2：启动 action server，处理自定义动作 rasa run actions --port 5055 # 终端 3：启动 Flask，对外提供网页和接口 python app.py--enable-api是必须的，否则 rasa 只做命令行交互不暴露 HTTP。--cors "*"是为了让 Flask 前端跨域调用，本地调试可以放开，上线要收紧。--port 5005是 rasa 默认端口，Flask 里如果写死了这个地址就别改。三个终端缺一不可，少一个 action server，涉及查数据库、调接口的意图就会返回空。
2.3 验证服务是否真的通了
服务起来后别只看日志有没有报错，用 curl 打一下 rasa 的模型接口，再用浏览器开 Flask 页面发一句话。
# 检查 rasa 是否加载了模型 curl http://localhost:5005/model # 发一条测试消息，看意图和实体识别结果 curl -X POST http://localhost:5005/model/parse \ -H "Content-Type: application/json" \ -d '{"text": "帮我查一下北京的天气"}'返回 JSON 里intent.name应该是类似query_weather，entities里应该有city: 北京。如果intent是nlu_fallback，说明模型没加载对或者 nlu 数据里没这个意图。这一步能过，再打开 Flask 页面输入同样的话，看机器人是否正常回复。常见翻车点是 Flask 里请求地址写成了127.0.0.1:5005但 rasa 只监听了localhost，或者反过来，改一下app.py里的RASA_API_URL即可。
3. 拆解对话管线：nlu、stories、actions 三块怎么改
3.1 nlu.md 里中文意图和实体的写法
rasa 的中文 NLU 训练数据全在data/nlu.md，格式是 Markdown 的## intent:xxx加例句，实体用[值](实体名)标注。这份源码里component_2_MitieEntityExtractor.dat说明作者用了 Mitie 做实体抽取，Mitie 对中文分词依赖jieba，所以config.yml里通常会有MitieTokenizer和MitieEntityExtractor两个组件。
## intent:query_weather - 帮我查一下[北京](city)的天气 - [上海](city)今天下雨吗 - 我想知道[广州](city)明天冷不冷 ## intent:book_ticket - 订一张去[杭州](city)的票 - 帮我买[明天](date)到[成都](city)的高铁改 nlu 数据时注意两点：一是实体标注的括号不能有空格，[北京](city)写成[北京] (city)就废了；二是每个意图至少 5 到 8 条例句，太少 Mitie 抽不出稳定特征。改完必须重新训练，不能指望热加载。
# 重新训练 NLU 和对话模型 rasa train # 训练完会在 models/ 下生成新的 tar.gz，替换启动命令里的模型路径rasa train会同时训练 NLU 和 Core，耗时取决于数据量，中文 Mitie 首次训练可能要几分钟。训练日志里如果出现No entity synonyms警告可以忽略，出现Failed to train NLU就要回去检查 nlu.md 的缩进和括号。
3.2 stories.md 与 domain.yml 的对应关系
stories.md描述对话流程，domain.yml定义意图、实体、槽位、动作和回复模板，两者必须严格对应。源码里的story_graph.dot就是 stories 的可视化图，用 Graphviz 可以转成 PNG 看整体走向。
# domain.yml 片段 intents: - query_weather - book_ticket entities: - city - date slots: city: type: text responses: utter_ask_city: - text: "请问你要查哪个城市的天气？" actions: - action_query_weather# stories.md 片段 ## weather path * query_weather{"city": "北京"} - action_query_weather - utter_goodbye槽位city在 domain 里定义后，stories 里{"city": "北京"}才能自动填充。如果 stories 里写了action_query_weather但 domain 的actions列表里没有，rasa 启动时会报ActionNotFoundException。改 stories 后同样要rasa train，只改 domain 的 responses 文本可以不重训，但改 actions 列表必须重训。
3.3 自定义 action 里怎么调外部接口
actions/actions.py是 Flask 和 rasa 真正干活的地方，比如查天气要调第三方 API，查订单要连数据库。写法是继承Action类，实现name和run方法。
from rasa_sdk import Action, Tracker from rasa_sdk.executor import CollectingDispatcher import requests class ActionQueryWeather(Action): def name(self): return "action_query_weather" def run(self, dispatcher, tracker, domain): city = tracker.get_slot("city") if not city: dispatcher.utter_message(text="请告诉我城市名") return [] # 这里替换成你实际可用的天气接口 resp = requests.get(f"http://your-weather-api.com/?city={city}", timeout=5) data = resp.json() dispatcher.utter_message(text=f"{city}今天{data['weather']}，{data['temp']}度") return []tracker.get_slot("city")拿的是 NLU 抽出来的实体自动填的槽位。dispatcher.utter_message把结果推回对话。return []表示不更新任何槽位，如果要更新就返回[SlotSet("key", value)]。注意requests一定要加timeout，否则外部接口挂了会把 action server 拖死，整个对话卡住。改完 actions.py 不用重训模型，但必须重启rasa run actions，因为 Python 代码不会热加载。
4. 避坑与常见问题排查：那些文档里不会写的翻车点
4.1 现象：rasa train 卡在 Mitie 模型下载
原因：Mitie 组件首次使用会去下载total_word_feature_extractor.dat，这个文件几百 MB，网络不稳就卡死。解决：手动下载后放到项目根目录，并在config.yml里指定本地路径。
- name: MitieEntityExtractor model: total_word_feature_extractor.dat4.2 现象：Flask 页面发消息没反应，控制台报 CORS
原因：rasa server 启动时没加--cors "*"，或者 Flask 请求头没带Content-Type: application/json。解决：重启 rasa 加上 cors 参数，Flask 侧用requests.post(url, json=payload)而不是data=payload，让 requests 自动设 header。
4.3 现象：意图识别总是 fallback，准确率极低
原因：nlu.md 里例句太少，或者中文没分词直接整句塞进去。解决：每个意图补到 8 条以上，确认config.yml里有MitieTokenizer且jieba已安装。另外检查训练时用的模型和启动时加载的模型是不是同一个 tar.gz，版本错位是高频翻车点。
4.4 现象：action server 报 500，日志显示 KeyError
原因：tracker.get_slot("xxx")拿的槽位在 domain.yml 里没定义，或者 stories 里没触发填充。解决：先在 domain.yml 的slots下补上该槽位，再在 stories 里确认有对应实体填充路径，最后重训。调试时可以在 action 里打印tracker.current_slot_values()看实际有哪些槽位。
4.5 现象：端口被占用，服务起不来
原因：5005 或 5055 被上次没关干净的进程占着。解决：lsof -i:5005找到 PID 后kill -9，或者启动时换端口，但换端口要同步改 Flask 里的请求地址，两边必须一致。
5. 进阶技巧：把对话数据导出做意图混淆矩阵与模型迭代
跑通之后真正有价值的一步，是把 rasa 的对话日志导出来做意图混淆分析，找出哪些意图总被认错，针对性补数据。rasa 支持把对话存到events数据库或 JSON 文件，我一般会在endpoints.yml里配一个 SQLite tracker store，然后写脚本拉出来跑混淆矩阵。
import sqlite3 import json from sklearn.metrics import confusion_matrix import pandas as pd conn = sqlite3.connect("rasa.db") cur = conn.cursor() # events 表里存的是对话事件流，取 user 消息和对应 intent cur.execute("SELECT sender_id, data FROM events WHERE type='user'") rows = cur.fetchall() pairs = [] for sender, data in rows: evt = json.loads(data) if "parse_data" in evt: text = evt.get("text", "") intent = evt["parse_data"]["intent"]["name"] confidence = evt["parse_data"]["intent"]["confidence"] pairs.append((text, intent, confidence)) df = pd.DataFrame(pairs, columns=["text", "intent", "confidence"]) # 低置信度样本优先看，这些就是该补数据的 low_conf = df[df["confidence"] < 0.6].sort_values("confidence") print(low_conf.head(20))这段脚本的逻辑是：从 SQLite 的 events 表里捞出所有用户消息，解析出 rasa 当时判定的意图和置信度，把置信度低于 0.6 的挑出来。这些样本就是模型「犹豫」的地方，人工看一眼，如果意图判错了就补进 nlu.md 对应意图，如果判对了但置信度低就补同义句。参数上0.6是经验阈值，低于它基本意味着模型在瞎猜，高于 0.9 的通常不用管。
除了混淆矩阵，还有一个我常用的习惯：每次rasa train之后把新模型在留出集上跑一遍rasa test，看DIETClassifier或MitieEntityExtractor的 F1 有没有掉。如果掉了，八成是新补的数据和旧数据分布冲突，比如同一个句子标了两个不同意图。rasa test会生成results/目录下的报告，里面有每个意图的 precision、recall 和混淆对，比肉眼看日志靠谱得多。
最后说个血泪经验：这份源码的20190618-115023.tar.gz是作者训练好的模型，但如果你改了 nlu.md 或 stories.md 却忘了重新rasa train，启动时还是加载旧模型，你会以为改了没用，然后反复怀疑人生。从那以后我每次改完数据都强制走一遍rasa train再启动，并且在 Flask 启动日志里打印当前加载的模型文件名，确认版本对得上。希望帮到你。
本文还有配套的精品资源，点击获取
