1. 为什么用 RNN/LSTM 做手写数字识别，而不是 CNN

很多人第一次接触 MNIST，默认就是卷积神经网络。卷积在图像任务上确实强，但如果你正在学循环神经网络，用 MNIST 练手其实是个很聪明的选择：它数据干净、标签明确、跑得快，能让你把注意力放在「序列建模」这件事本身，而不是被数据清洗拖住。

那问题来了，一张 28×28 的静态图片，哪来的「序列」？关键在于视角转换。你可以把一张手写数字图看成 28 行像素，从上到下依次读入。每一行是一个 28 维向量，28 行就构成一个长度为 28 的时间序列。LSTM 在读完第 28 行后，最后一个时间步的隐藏状态就浓缩了整张图的笔画走向信息，再接到一个 28→10 的全连接层，就能输出 0 到 9 的分类概率。

这个思路的价值在于：它让你真正理解time_step_size、num_units、state_is_tuple这些参数到底在控制什么。CNN 里你调的是卷积核、步长、通道数；RNN 里你调的是时间步长度、单元数、状态传递方式。两者是两套完全不同的心智模型。

适合谁看这篇？如果你已经会写基本的 TensorFlow 图，能看懂 placeholder 和 session，但一遇到tf.split、static_rnn、MultiRNNCell就发懵，那这篇就是给你准备的。我会从数据加载一路写到训练评估，把每个容易踩坑的地方都标出来。实测下来，这套结构在 MNIST 上跑到 96% 到 98% 的测试准确率是稳的，再往上就要靠调参和加层了。

需要说明的是，本文代码基于 TensorFlow 1.x 的tf.contrib.rnn接口，这是当年最经典的写法。如果你用的是 TF2，tf.contrib已经被移除，需要迁移到tf.keras.layers.LSTM，但底层原理完全一致，理解了这里的每一步，迁移只是换 API 的事。

另外，训练过程中如果你想让模型帮你解释某段报错、或者生成调参建议，可以借助大模型对话来加速排查，后面我会提到怎么把这类工具接进你的工作流。

2. 环境准备与 TaoToken 接入前置配置

在动手写模型之前，先把运行环境和一个能帮你排障的模型服务准备好。这一节不是可有可无的铺垫，因为后面训练脚本一旦报错，你需要一个能快速问清楚的通道，而不是在搜索引擎里翻半天。

先说 TensorFlow 环境。推荐用 Python 3.7 到 3.8 配 TensorFlow 1.15，这是tf.contrib.rnn还能正常工作的最后一个稳定版本。用 conda 建一个独立环境最省心：

conda create -n rnn_mnist python=3.8 conda activate rnn_mnist pip install tensorflow==1.15.0 numpy

装完之后验证一下：

python -c "import tensorflow as tf; print(tf.__version__)"

能打印出 1.15.0 就说明环境没问题。如果你装的是 TF2，from tensorflow.contrib import rnn这一行会直接报ModuleNotFoundError，这是最常见的第一个坑，后面排障章节会细说。

接下来是模型服务的前置配置。训练脚本本身不依赖外部服务，但当你想让模型帮你分析报错日志、解释static_rnn的输出形状、或者生成一段调参代码时，一个稳定的 API 入口会省很多时间。TaoToken 提供统一的 API 地址，你只需要拿到 Key 并配好 Base URL 就能调用。

第一步，打开控制台创建 API Key。访问 https://taotoken.net/api-keys ，登录后新建一个 Key，复制保存好，它只显示一次。

第二步，配置 Base URL。所有请求都走 https://taotoken.net/api 这个地址，注意它和官网首页不是同一个路径，别填错。

第三步，选模型。做代码排障和解释，用对话类模型就够了，可以在模型对话页面先试一下效果：https://taotoken.net/models 。如果你打算长期做编码和 Agent 类任务，可以了解 Coding Plan：https://taotoken.net/coding-plan 。

把这三样东西记下来，后面配置里会用到：

如果你用的是 Claude Code 这类命令行工具，接入方式略有不同，需要设置环境变量指向 Anthropic 兼容端点，具体可以参考接入文档：https://taotoken.net/doc 。文档里有完整的 Base URL、Key、Model ID 三件套说明，照着填就行。

注意：API Key 属于敏感凭证，不要硬编码进提交到 Git 的脚本里。建议用环境变量读取，或者放在本地.env文件中并加入.gitignore。

环境和服务都备齐后，我们就可以进入正题，开始写模型了。

3. 可复制的 LSTM 模型配置与训练脚本骨架

这一节是全文的核心，我会把完整的脚本拆成几块讲清楚，每一块你都可以直接复制运行。先给一个整体结构：数据加载 → 形状变换 → 构建 LSTM → 接全连接输出 → 定义损失和优化器 → 训练循环 → 评估。

先看数据加载和形状变换。MNIST 原始数据是 55000 张 784 维的扁平向量，我们要把它还原成 28×28，再按时间步切分。

# -*- coding: utf-8 -*- import tensorflow as tf from tensorflow.contrib import rnn import numpy as np import input_data # 配置参数 input_vec_size = lstm_size = 28 # 每行像素维度，也是 LSTM 单元数 time_step_size = 28 # 时间步长度，即 28 行 batch_size = 128 test_size = 256 mnist = input_data.read_data_sets("MNIST_data/", one_hot=True) trX, trY = mnist.train.images, mnist.train.labels teX, teY = mnist.test.images, mnist.test.labels # 还原成 28x28 trX = trX.reshape(-1, 28, 28) teX = teX.reshape(-1, 28, 28)

这里input_data.py是经典的 MNIST 加载脚本，如果你没有，可以从 TensorFlow 旧版示例里找到，或者用tf.keras.datasets.mnist替代后手动做 one-hot。

接下来是模型定义，这是最容易出错的地方，我逐行注释：

def init_weights(shape): return tf.Variable(tf.random_normal(shape, stddev=0.01)) def model(X, W, B, lstm_size): # X 形状: (batch_size, time_step_size, input_vec_size) # 转置成 (time_step_size, batch_size, input_vec_size) XT = tf.transpose(X, [1, 0, 2]) # 拉平成 (time_step_size * batch_size, input_vec_size) XR = tf.reshape(XT, [-1, lstm_size]) # 按时间步切成 28 个 (batch_size, input_vec_size) 的数组 X_split = tf.split(XR, time_step_size, 0) # 定义基础 LSTM Cell lstm = rnn.BasicLSTMCell(lstm_size, forget_bias=1.0, state_is_tuple=True) # 包一层 Dropout，只对输出做 dropout lstm = tf.nn.rnn_cell.DropoutWrapper(lstm, output_keep_prob=keep_prob) # 堆叠多层，这里 num_layers=2 lstm = tf.nn.rnn_cell.MultiRNNCell([lstm] * num_layers, state_is_tuple=True) # static_rnn 返回每个时间步的输出 outputs, _states = rnn.static_rnn(lstm, X_split, dtype=tf.float32) # 只取最后一步输出接全连接 return tf.matmul(outputs[-1], W) + B, lstm.state_size

几个关键点必须说清楚。num_units指的是一个 Cell 内部神经元的个数，不是循环层的层数。循环层的「长度」由time_step_size决定，也就是X_split切出来的数组个数。这两个概念新手极容易混。

state_is_tuple=True一定要加。它让 LSTM 的内部状态c和h以二元组形式返回，而不是拼接成一列。官方早就说拼接形式要废弃，不加这个参数未来会报错。

DropoutWrapper在 RNN 里的行为和 CNN 不同。时间序列方向上不做 dropout，只对每一层传给下一层的输出做 dropout，也就是output_keep_prob控制的那部分。这样不会破坏时间上的记忆传递。

MultiRNNCell用来堆叠多层。[lstm] * num_layers会生成一个列表，但要注意这里其实是同一个 Cell 对象被引用多次，在旧版里可能引发变量共享问题，更稳妥的写法是用列表推导每次新建：

cells = [tf.nn.rnn_cell.BasicLSTMCell(lstm_size, state_is_tuple=True) for _ in range(num_layers)] lstm = tf.nn.rnn_cell.MultiRNNCell(cells, state_is_tuple=True)

然后是损失、优化器和训练循环：

X = tf.placeholder("float", [None, 28, 28]) Y = tf.placeholder("float", [None, 10]) keep_prob = tf.placeholder("float") num_layers = 2 W = init_weights([lstm_size, 10]) B = init_weights([10]) py_x, state_size = model(X, W, B, lstm_size) cost = tf.reduce_mean(tf.nn.softmax_cross_entropy_with_logits(logits=py_x, labels=Y)) train_op = tf.train.RMSPropOptimizer(0.001, 0.9).minimize(cost) predict_op = tf.argmax(py_x, 1) session_conf = tf.ConfigProto() session_conf.gpu_options.allow_growth = True with tf.Session(config=session_conf) as sess: tf.global_variables_initializer().run() for i in range(100): for start, end in zip(range(0, len(trX), batch_size), range(batch_size, len(trX)+1, batch_size)): sess.run(train_op, feed_dict={ X: trX[start:end], Y: trY[start:end], keep_prob: 0.5}) test_indices = np.arange(len(teX)) np.random.shuffle(test_indices) test_indices = test_indices[0:test_size] acc = np.mean(np.argmax(teY[test_indices], axis=1) == sess.run(predict_op, feed_dict={ X: teX[test_indices], keep_prob: 1.0})) print("Epoch", i, "Accuracy", acc)

注意keep_prob在训练时设 0.5，评估时必须设 1.0，否则结果会偏低。这是很多人第一次跑出来准确率只有 80% 多的原因。

如果你想把这段配置存成结构化文件方便复用，可以用 JSON 记录超参：

{ "input_vec_size": 28, "lstm_size": 28, "time_step_size": 28, "batch_size": 128, "num_layers": 2, "learning_rate": 0.001, "decay": 0.9, "keep_prob_train": 0.5, "keep_prob_eval": 1.0, "epochs": 100 }

把路径和参数对齐后，脚本就能稳定复现。这套骨架跑通后，你会发现改num_layers和lstm_size对结果影响很明显，这就是调参的乐趣所在。

4. 验证请求与成功结果：准确率怎么读、日志怎么看

脚本跑起来之后，控制台会每个 epoch 打印一行准确率。第一次看到输出时，你要能判断它是否正常。

典型的正常输出长这样：

Extracting MNIST_data/train-images-idx3-ubyte.gz Extracting MNIST_data/train-labels-idx1-ubyte.gz Epoch 0 Accuracy 0.8515625 Epoch 1 Accuracy 0.91015625 Epoch 2 Accuracy 0.93359375 ... Epoch 20 Accuracy 0.97265625 Epoch 50 Accuracy 0.98046875

前几个 epoch 准确率爬升很快，从 85% 到 93% 通常只要两三轮，之后进入缓慢提升期，最终稳定在 97% 到 98% 之间。如果你看到第 0 轮就只有 10% 左右，那基本是输出层或标签对不上；如果一直卡在 90% 出头不涨，多半是keep_prob评估时没设成 1.0，或者学习率太大导致震荡。

想更直观地看训练过程，可以加一段可视化，把测试集里预测错的样本挑出来：

# 找出预测错误的样本 preds = sess.run(predict_op, feed_dict={X: teX, keep_prob: 1.0}) labels = np.argmax(teY, axis=1) wrong = np.where(preds != labels)[0] print("Wrong count:", len(wrong)) print("First 10 wrong indices:", wrong[:10])

跑完你会看到错误样本数量大概在几百个量级（测试集 10000 张，98% 准确率对应约 200 个错误）。把这些索引对应的图片打印出来，你会发现错的大多是书写极其潦草、或者 4 和 9、3 和 8 这种本身就难分的样本。这说明模型已经学到了合理的特征，不是随机猜。

如果你想验证模型对单张图的推理，可以这样写：

sample = teX[0:1] # 取第一张测试图 result = sess.run(predict_op, feed_dict={X: sample, keep_prob: 1.0}) print("Predicted:", result[0], "True:", np.argmax(teY[0]))

这一步能帮你确认推理路径和训练路径用的是同一套图，避免出现「训练准、推理错」的诡异情况。

关于日志，TensorFlow 1.x 启动时会刷一堆 warning，比如deprecation提示、GPU 相关提示，这些大多可以忽略。真正要盯的是有没有Error或Traceback。如果训练中途 loss 变成nan，通常是学习率过大或者输入没归一化，MNIST 像素本身在 0 到 1 之间，一般不会出这个问题，但如果你自己换了数据集就要注意。

实测下来，这套配置在普通 CPU 上跑 100 个 epoch 大概十几分钟，GPU 上几分钟就完事。如果你想让模型帮你解读某段异常日志，可以把报错原文贴到模型对话里问，比逐字搜索快得多。

5. 本篇常见报错排查：401、形状不匹配、OAuth 与代理问题

这一节把跑这个脚本时最可能撞上的错误集中列出来，每个都给出定位思路和修复动作。

报错一：ModuleNotFoundError: No module named 'tensorflow.contrib'

这是 TF2 环境跑 TF1 代码的典型症状。tf.contrib在 TF2 里被彻底移除。两个解法：要么降级到 TF 1.15，要么把rnn.BasicLSTMCell换成tf.keras.layers.LSTMCell，static_rnn换成tf.keras.layers.RNN或手动展开循环。降级最快，迁移更长远。

报错二：ValueError: Shape must be rank 3 but is rank 2

多半是tf.split或tf.transpose的维度搞错了。检查X的 placeholder 是不是[None, 28, 28]，tf.transpose(X, [1, 0, 2])之后应该是(28, batch, 28)。如果你把 reshape 写成了(-1, 784)，后面全乱。打印XT.shape和XR.shape确认。

报错三：InvalidArgumentError: ConcatOp : Dimensions of inputs should match

这个通常出在MultiRNNCell堆叠时，各层state_size不一致。确保每个 Cell 的lstm_size相同，并且都设了state_is_tuple=True。如果混用了 tuple 和 non-tuple，状态拼接时维度对不上就会报这个。

报错四：调用 API 时返回 401 Unauthorized

如果你在脚本里集成了模型服务做日志分析，401 说明 Key 无效或没带上。检查请求头里Authorization: Bearer <你的Key>是否正确，Base URL 是不是https://taotoken.net/api。Key 复制时容易多带空格，重新从控制台复制一次。

报错五：local proxy failed或连接超时

这类错误一般是本地网络配置或环境变量干扰。检查有没有设置HTTP_PROXY、HTTPS_PROXY这类环境变量，如果有就临时清掉再试。请求地址要确保是官方 API 端点，不要填成别的路径。

报错六：OAuth 相关报错，比如invalid_grant或token expired

如果你用的是 Claude Code 这类需要 OAuth 授权的工具，token 过期是常见原因。重新走一遍授权流程，或者检查系统时间是否准确，时间偏差过大会导致 token 校验失败。接入文档里有完整的授权步骤，照着走一遍即可。

报错七：reading choices相关解析错误

这通常出现在你解析模型返回的 JSON 时，字段路径写错了。返回体里choices是个数组，取第一个元素的message.content。如果你直接按字符串处理整个响应，就会解析失败。打印原始响应体看一眼结构，再决定怎么取字段。

报错八：准确率评估异常低

先确认评估时keep_prob是不是 1.0。再确认predict_op用的是argmax(py_x, 1)，而标签是 one-hot，比较时要先argmax(teY, axis=1)。这两处任一写错，准确率都会掉到随机水平。

把上面这些对照着排查，基本能覆盖 90% 的卡点。剩下的边角问题，把完整 traceback 贴给模型问，通常几轮就能定位。

6. 把 LSTM 训练接进你的日常开发流

跑通这个脚本只是起点。真正有价值的是把它变成你随手能改、能复用的模板。我的习惯是把数据加载、模型定义、训练循环拆成三个文件，超参全部抽到配置文件里，这样换数据集时只改数据层，换模型结构时只改模型层。

如果你后续要做更复杂的序列任务，比如文本分类、时间序列预测，这套 LSTM 骨架可以直接迁移，只需要把输入从 28 行像素换成词向量序列或传感器序列，输出层维度改成你的类别数。time_step_size和lstm_size这两个参数是调优的主战场，前者决定模型能看多长的上下文，后者决定每个时间步的记忆容量。

训练过程中遇到报错、想对比不同超参的效果、或者需要生成一段数据预处理代码时，把模型对话接进工作流会明显提速。你可以在 https://taotoken.net/models 先试几个模型，找到适合代码场景的那个，再去 https://taotoken.net/api-keys 创建 Key，配合 https://taotoken.net/doc 里的接入说明配置到你的脚本或工具里。长期做编码和 Agent 任务的话，Coding Plan 会更划算，地址是 https://taotoken.net/coding-plan 。

最后留一个实用技巧：训练前先用小批量数据跑通全流程，比如只取 1000 张图、跑 2 个 epoch，确认没有形状错误和 API 报错，再放开全量数据。这样能把调试时间从半小时压缩到几分钟。等这套流程顺了，你会发现 RNN 系列模型并没有想象中那么难上手，难的是把每个参数的物理意义搞清楚，而 MNIST 恰好是最好的练手场。