Stata调用大模型：catllm实现文本分类与主题发现实战

做实证研究的人应该都经历过这样的夜晚：三千条开放题回答摆在面前，每一段都要人工编码，而明天就要交初稿。我那时一边盯着一家企业客服投诉数据，一边在Stata里来回翻看，忍不住去搜“Stata 调用大模型”，然后找到了catllm这个命令。简单说，catllm把大语言模型的API接到了Stata内部，让文本分类、主题发现这类事不用离开当前数据集就能做。这篇文章我会从安装、密钥配置、命令语法讲起，再用两个真实场景——文本分类和主题发现，展示它怎么嵌入标准的数据分析流程。最后会聊一批我在实际使用中踩过的坑，以及如何把模型分类结果接回reghdfe这类常规计量分析里。

1. 为什么我最终决定在Stata里直接调用大模型

过去处理非结构化文本，我的方案基本是三条路：人工编码、词典法、把数据导出到Python再导回来。人工编码最准但也最贵，几百条还能忍，几千条就真的会让人怀疑人生。词典法比如LIWC，处理情绪词还行，一旦涉及“投诉属于退款问题还是物流问题”这种需要语义理解的分类，词典法就彻底不够用了。至于Python，我本身不是不能写，问题在于项目里从清洗到回归的完整流程都在Stata里，为了文本分类单独开一条Python流水线，意味着要重新管理数据交接、环境依赖、并行任务，麻烦程度远超过文本分类本身。

第一次看到catllm时，我其实不太相信它能用。后来想明白了一件事：大模型API本质上就是一个HTTP请求，你给我文本，我返回文本。既然Stata能做HTTP，那在Stata里封装一个命令就是顺理成章的事。catllm做的就是这个封装：你把一个文本变量传给它，构造一段prompt，它调用模型API，再把模型返回的结果放回到Stata的r()宏里，方便你写到新变量中。整个过程不需要退出Stata，不需要懂HTTP协议，甚至不需要会写Python。对于我这种“数据清洗和回归必须在Stata里完成”的强迫症用户来说，这条路径几乎是量身定做的。

不过要先把预期管理好。catllm不是文本挖掘的全家桶，它不负责分词、不负责停用词、不负责训练模型，更不会自动生成一篇论文。它只是把“调用大模型”这件事在Stata环境里做成了一个可复用的命令。真正的分析思路、分类体系、提示词设计、结果校验，仍然全部是你自己的事。换句话说，它把“从外部搬运数据”的体力活省掉了，但“怎么提问、怎么确认答案靠谱”的脑力活一分都不会少。

这篇文章适合谁呢？主要是靠Stata吃饭的实证研究者、社科领域数据分析师，以及那些手里有一堆文本字段但一直不知道如何系统利用它们的人。如果你已经熟悉Python和大模型API，那这整篇内容对你来说可能偏基础；但如果你希望在不更换主力工具的前提下完成文本分类与主题发现，catllm会是一个非常值得加入工具箱的选项。

2. 从安装到第一次连通：catllm环境准备

2.1 安装命令与版本依赖

安装本身不复杂，直接在Stata里执行：

ssc install catllm

我安装的版本需要Stata 16及以上，因为底层要借助Stata的Python集成来发HTTP请求。装完之后可以先确认环境没问题：

python which

如果这步能正常返回Python路径，说明Stata的Python通道是可用的。顺便说一句，国内用户如果发现默认Python版本不太对，或者ssc install偶尔连接不稳定，可以先检查Stata的网络代理设置，也可以从GitHub上的发布页直接下载安装包，把catllm.ado和相关文件放到个人ado目录里。

2.2 API密钥的三种放法

调用大模型API必须有密钥，密钥管理是值得认真对待的一件事。我习惯用环境变量方式：

setenv OPENAI_API_KEY "sk-你的密钥"

setenv只对当前Stata会话有效，关掉软件就失效，安全性相对好。第二种方式是把密钥写进系统环境变量，这样任何会话都能读到，适合长期使用。第三种方式是直接在命令里用api_key()选项传密钥，比如catllm, api_key("sk-xxx")。我非常不建议最后一种做法，因为密钥一旦写进do文件，后面又分享代码或者推到GitHub，密钥就等于公开了。后面踩坑部分我会专门说这个事。

2.3 第一次连通性测试

配置好密钥后，跑一条最简单的指令：

catllm, model("gpt-4o-mini") prompt("用一句话回答：你是什么模型？") display "`r(text)'"

如果屏幕上能看到模型返回的自我介绍，说明Stata和大模型的连接已经打通。这里返回结果存放在r(text)宏里，不同版本的catllm可能还提供r(response)等别名，建议调用一次后先执行return list看看到底有哪些返回值。

如果你不想用云端API，catllm同样支持自定义端点。我试过把本地的Ollama服务接进来，调用本地部署的开源模型，比如Qwen系列。大致写法如下：

catllm, model("qwen2.5:7b") endpoint("http://localhost:11434/v1") api_key("ollama") prompt("你好，请简短回复。")

这样做的意义在于，如果你的文本数据涉及隐私，不方便传到云端，本地部署就是合理替代方案。密钥字段在本地端点上通常只是一个占位符，填ollama仅是习惯用法，具体以你使用的本地服务说明为准。

2.4 常见连通失败的排查

第一次连接大概率不会一次成功，我把最常见的几类问题整理成一张表，方便对照排查：

我的经验是：第一次连通花最多时间的地方反而不是Python环境，而是密钥和模型名的拼写。因此不要一上来就批量跑，先确保能正常返回一条结果，再上线正式任务。

3. 命令语法与参数速查：看懂catllm在做什么

3.1 语法骨架

catllm看上去参数不少，核心结构大致是这样的：

catllm, model(...) prompt(...) [text(...) temperature(...) max_tokens(...) endpoint(...) api_key(...) timeout(...) retry(...)]

model()指定模型，prompt()是发给模型的核心指令，text()用来传数据集里的某个文本变量。如果没有text()，catllm就单纯把prompt()发给模型；如果有了text()，它会自动把文本拼接进prompt一起发送。返回值放在r()宏里，等待下一步处理。

3.2 prompt是如何被组装起来的

理解拼接规则很重要。我测试下来的结果是：当你同时写prompt()和text()时，catllm会把两者组合成一个完整请求。比如：

catllm, model("gpt-4o-mini") prompt("请对下面的评论做情感分类，只输出正面、负面或中性：") text(comment) temperature(0)

实际发送给模型的文本，相当于“请对下面的评论做情感分类，只输出正面、负面或中性：”再加上该条评论的内容。想验证这一点，可以在提示词里加一句“用户输入如下：”，然后用一个简单的文本变量测试输出。我发现很多早期失败都源于对拼接顺序的误解，有人以为text()里的内容会被单独处理，结果模型把整段话当成一体，输出就变得不可控。

3.3 返回结果与存入数据变量

调用完成后，可以用return list查看catllm返回了哪些宏。通常会有文本结果，也可能有JSON结构化结果。想要把结果写进变量，最直接的方式是在循环里逐条保存：

gen pred = "" forvalues i = 1/10 { local t = comment[`i'] catllm, model("gpt-4o-mini") prompt(`"请对下面的评论做情感分类，只输出正面、负面或中性："') text(`"`t'"') temperature(0) replace pred = `"`r(text)'"' in `i' }

这里的两个细节值得留意。第一，text()里我用"'把t包住，是为了防止文本里的空格导致参数解析出错。第二，保存时用`"`r(text)'"'把返回值包成Stata字符串，避免因为返回内容里包含逗号或引号而破坏replace命令。早期的版本没有这种保护的话，遇到含引号的文本会报错。

3.4 关键参数的默认值与作用

关于temperature，我自己的体会是：分类和打标签这种封闭型任务，温度调低有立竿见影的效果，0和1之间的差异往往比换模型更明显。但主题发现这种开放型任务，温度太低会导致每次输出的关键词都差不多，缺少多样性，反而不利于发现隐藏维度。先明确任务性质，再决定温度，不要一个参数走天下。

4. 文本分类实战：把人工编码变成模型编码

4.1 先定好分类体系，再写给模型看

文本分类的第一步不是写代码，而是把分类体系定清楚。我当时处理的是投诉数据，类别定为：退款、物流、质量、客服态度、其他。分类体系看起来简单，但模型和人一样，最怕模糊的类目。如果只说“请把投诉分类”，模型很可能把“东西坏了”归到“产品问题”，又把“想退货”归到“售后问题”，标准不统一。

我最后用到的提示词模板大致是：

你是一名客户服务质检员。请将下面的投诉文本归入以下五类之一：退款、物流、质量、客服态度、其他。规则： 1. 如果文本同时涉及多个类别，选择最核心的那个。 2. 只输出一个类别名称，不要解释，不要加标点。 3. 无法判断时输出“其他”。

补充这些规则不是凑字数，而是有实际作用的。第一，明确“只输出一个类别名称”，能避免模型输出“这属于退款问题吧？”这种多余内容。第二，给出“无法判断时输出其他”，实际上是给模型留了安全出口，让它不必硬猜。你会发现，加了这个安全出口之后，整体准确率反而会提升，因为模型不再为了强行归类而犯低级错误。

4.2 批量分类的循环写法

小范围验证提示词没问题后，再放大到全样本。Stata里最稳的批量写法就是循环：

use complaints.dta, clear gen pred = "" gen clean_comment = subinstr(comment, char(10), " ", .) forvalues i = 1/`=_N' { local txt = clean_comment[`i'] cap catllm, model("gpt-4o-mini") prompt(`"你是一名客户服务质检员。请将下面的投诉文本归入以下五类之一：退款、物流、质量、客服态度、其他。规则：只输出一个类别名称，不要解释，无法判断时输出其他。文本如下："') text(`"`txt'"') temperature(0) retry(2) if _rc == 0 { replace pred = `"`r(text)'"' in `i' } }

我在循环里加了两处防御。一是用subinstr把文本里的换行符替换成空格，这能避免多行文本破坏请求格式；二是用cap catllm捕获错误，即使某次网络调用失败，也不会让整个循环中断。失败的记录会保持为空值，下一节会讲怎么用断点续跑补上。

4.3 质量评估：抽样复核与Kappa

模型分类做完不代表完事。我强烈建议抽一个随机子样本，做人工复核，然后计算一致性指标。比如随机抽100条，人工标好类别后：

tab human pred kap human pred

kap计算的是Cohen's Kappa，取值在-1到1之间。我个人的判断标准比较朴素：高于0.7说明模型编码和人工编码有较强一致性，可以放心把模型当主力；低于0.5则说明提示词或分类边界还有问题，与其加钱换大模型，不如回头调整分类体系。这里有一个反直觉的经验：很多时候问题不是模型不够聪明，而是分类体系自身重叠严重，比如“物流”和“售后”在投诉语境里边界模糊。把类目描述写得更具体，效果立竿见影。

4.4 迭代改进的思路

第一次跑出来的结果往往不尽如人意，但没关系，迭代空间很大。我发现比较有效的做法是：把错误案例拆出来看。比如模型把“快递丢了要求赔偿”归入“退款”，而人工标注是“物流”，那可能是提示词里缺了一条规则——“涉及运输环节异常的，一律归物流”。把规则补充进提示词，重跑错误案例，确认改了，再跑全量。这个过程听起来很土，但确实是我用过最稳定的分类质量提升路线。

5. 主题发现实战：从非结构化文本中提炼可检验的主题

5.1 主题发现与分类任务的区别

分类任务是一个封闭集问题：类别给定，你只需要让模型做选择题。主题发现则是开放集问题：文本里到底有哪些主题，你需要让模型帮你提炼出来。这要求提示词写法完全不同。分类时我会把温度调低，但主题发现时，我会把温度保持在0.7左右，目的是让模型能跳出惯性输出，给出一些意想不到的角度。

5.2 两轮提示法：先关键词后主题

我的主题发现流程分两轮。第一轮让模型从每段文本里提取关键词，不要求做任何判断，任务非常轻：

请从下面的开放式回答中提取2到3个关键主题词，用逗号分隔。只输出关键词，不要输出句子。

第二轮是把所有关键词拿回来之后，在人机协作下确定主题标签。比如员工反馈数据里反复出现“食堂”“加班”“晋升”，这三个关键词对应“福利保障”“工作强度”“职业发展”等主题。与其让模型一口吃成个大胖子，不如先做信息抽取，再做人工聚合。这样每一步都可控，也方便检验。

5.3 用split和collapse整理标签

第一轮输出的是逗号分隔的关键词串，存入变量后，用Stata的split命令就能快速展开：

split keywords, parse(",")

展开之后得到keywords1、keywords2、keywords3几个变量，再通过reshape或stack把它们整合成长表，就可以统计词频了。这里要注意，模型可能用同义词表达同一个概念，比如“工资”“薪资”“薪酬”本质是一个主题。所以严格来说，关键词统计之后还必须做一轮近义合并，这一步我目前没有找到完全自动化的方法，基本靠人工维护一个同义词映射表。别嫌麻烦，主题发现的真正价值恰恰在这轮整理里。

5.4 主题质量校验的一个真实教训

有一回我处理开放式问卷反馈，模型给“食堂菜品种类少”和“食堂开放时间短”都提取了“食堂”作为关键词。从提取角度看，模型完全正确。但问题来了：放在主题库里，“食堂”既不代表好评也不代表差评，它只是一个中性的场景词。真正有分析价值的主题应该是“餐饮服务质量”或“后勤保障满意度”。这说明关键词层面正确，不代表主题层面正确。后来我调整了提示词，要求模型不仅提取关键词，还要判断这个关键词对应的态度倾向，比如“食堂-负面”。这个改动让主题库的实用价值大了很多。

6. 批量处理的性能与成本：面对一千条文本的操作方案

6.1 先理解延迟曲线

单次调用大模型API，延迟通常在1到3秒。遇到模型负载高或者文本很长，5秒也不奇怪。按每条2秒计算，一千条也就是三十多分钟，看起来可以接受。但实际跑的时候你会遇到接口限流，连续高频请求很容易触发429错误或连接重置。所以批量处理第一课是：别指望一口气跑完，要设计能中断、能续跑的任务。

sleep 100

在循环末尾加一个sleep 100毫秒的小停顿，成本极低，却能明显减少限流概率。样本量几千条以内，我建议老老实实单线程跑，配合去重和续跑，比折腾并发更省心。

6.2 成本估算与模型价格

成本取决于模型单价和文本长度。一段200字的投诉，加上提示词，一次调用大概消耗300到500个token。以目前主流轻量模型的价位来看，每百万输入token的定价大约在1到3元人民币量级，每次调用折合人民币不到一分钱。一千条文本全量跑下来，花费通常也就是几元到几十元。更贵的旗舰模型单价会高一个数量级，但分类任务用轻量模型足够。我的经验是：先用便宜模型跑通流程，确认效果达标后，再决定要不要升级模型，这个顺序不要反过来。

6.3 去重、重试、断点续跑三条军规

第一条军规是去重。文本数据里重复率往往比你想象的高，尤其是客服记录和问卷反馈。先做唯一化：

duplicates tag clean_comment, gen(dup)

把重复样本挑出来，只对每个唯一文本调用一次API，再把结果合并回去。这样能直接省掉百分之几十的调用量。

第二条军规是重试。网络请求不可能百分之百成功，retry(2)这类参数可以让命令在遇到临时失败时自动重试，避免进程中断。

第三条军规是断点续跑。原理很简单：循环里使用cap catllm，失败时结果变量为空，跑完整个脚本后，只对缺失值重新调用：

forvalues i = 1/`=_N' { if missing(pred[`i']) & !missing(clean_comment[`i']) { local txt = clean_comment[`i'] cap catllm, model("gpt-4o-mini") prompt(`"..."') text(`"`txt'"') temperature(0) if _rc == 0 { replace pred = `"`r(text)'"' in `i' } } }

有了这三条军规，一千条文本的任务基本不需要人盯着，跑完了看日志补漏就行。

6.4 当样本量更大时怎么办

样本量到了几万条，单线程循环就会变得很煎熬。我的建议不是硬写并发脚本，而是用Stata的preserve、restore或outsheet把数据按ID分块导出，同时打开几个Stata实例，每个实例跑一部分，最后再合并。这样做的好处是不用改任何代码，只需要改样本范围。如果你不想手动开多个窗口，也可以用Python写一个并发调用的脚本，但那就偏离本文主题了。对我而言，Stata单线程的“笨办法”配合去重和续跑，已经解决了绝大多数实务问题。

7. 踩坑记录：编码、Token、密钥与幻觉

7.1 文本清洗：换行符与引号

文本变量最常见的隐形杀手是换行符。从Excel或数据库中读进来的文本，经常包含char(10)换行，这会让请求内容被拦腰截断，甚至改变提示词语义。我的固定加法是：

gen clean_text = subinstr(textvar, char(10), " ", .) replace clean_text = subinstr(clean_text, `"""', "", .)

把换行符替换成空格，把双引号去掉，不要让用户原始文本里那些无规律的符号干扰API请求结构。做完清洗再入循环，错误率会肉眼可见地下降。

7.2 中文编码与UTF-8

中文乱码问题也很常见。Stata 14以后默认支持UTF-8，但很多旧数据的编码是GBK等本地编码。处理方法是在读入数据前就设定好编码：

unicode encoding set utf-8 unicode translate textvar

如果你发现模型返回结果里的中文正常，但原始文本传进去的是乱码，那多半就是数据文件编码没对齐。建议在正式批量之前，随便抽一条文本打印出来看看，确认中文显示正常再开工。

7.3 Token超限与分段

超长文本很容易触发最大长度限制。处理办法之一是截断：

gen truncated = substr(clean_text, 1, 500)

但截断会丢失信息，如果模型任务是判断整篇文档的主题，只取前500字可能有偏。更稳的办法是分段调用，把长文本按段落拆开，分别提取信息后再汇总。我处理过一批年度报告，单篇好几千字，我就是按段落调用的。要注意的是，分段调用意味着多次计费，成本要提前算清楚。好在这种任务通常不需要大批量处理。

7.4 密钥安全没有侥幸

这一条我想讲得重一点。把API密钥直接写在do文件里，然后把do文件上传到GitHub，等于把钱包密码公开。我见过不止一次因为密钥泄露导致账户被刷掉大额费用的案例。保护自己的方式很简单：密钥放环境变量，do文件里只写setenv OPENAI_API_KEY "..."这种从环境读取的代码；上传代码前把包含真实密钥的do文件排除掉。如果你用Git管理代码，可以设置.gitignore，把*.do里的密钥文件排除在版本控制之外。密钥泄露后的补救手段极其有限，最好的策略是不让它发生。

7.5 模型幻觉和一致性复检

我把幻觉问题放在最后一个写，是因为它是最隐蔽的坑。模型可能一本正经地把一条“商品和描述相符”的评论归成“负面”，因为它在语义联想里捕捉到了某种不存在的讽刺。更麻烦的是，同一个文本调用两次，结果可能不同。即使temperature(0)，也不能保证百分百一致。所以当分类结果要作为论文核心变量时，建议对关键样本做两次甚至三次调用，取多数结果作为最终编码。这不是小题大做，而是把模型的不可靠性暴露出来并摊平它。

8. 把分类结果接回标准计量流程：reghdfe、面板数据与亚组分析

8.1 生成可回归变量

文本分类的最终目的通常是进入统计分析。pred这个字符串变量没办法直接做回归，需要先编码成数值变量：

encode pred, gen(sentiment) tab sentiment

encode会按字符串值生成数字标签，比如“负面”对应1、“中性”对应2、“正面”对应3。编码后的变量可以直接作为被解释变量或解释变量使用。

8.2 在固定效应回归中使用

如果你手里的数据是面板结构，比如企业季度数据，那么分类结果最常见的归宿就是固定效应模型。执行标准流程：

xtset firm quarter reghdfe y sentiment controls, absorb(firm quarter) vce(cluster firm)

这里的y可以是经营结果，sentiment就是从文本分类中提取的核心解释变量，controls是其他控制变量。reghdfe能处理高维固定效应，在顶刊实证里几乎是标配。之前文本变量只是躺在数据集里的一列字符串，经过catllm分类和encode之后，它变成了可以放进回归方程的正式变量。这一步对实证研究者来说，意义远大于分类本身。

8.3 面板数据、缺失与插补

面板数据还有一个常见问题是文本字段缺失。有时候一个企业某季度没有留下文本记录，分类结果自然也无法生成。这时候你面临的选择是：直接缺失，还是用面板插补技术补上。我想提醒的是，模型分类结果本质上已经是带有测量误差的变量，如果再用插补法把它填平，误差会被进一步放大。稳妥的做法是，先把缺失原因搞清楚，再决定是否使用mi impute等命令补全。如果缺失完全随机，插补问题不大；如果缺失和结果变量相关，那插补反而会引入严重偏差。这类问题没有标准答案，需要结合具体研究场景处理。

8.4 亚组比较中的注意事项

热搜词里有人搜“亚组分析”，这里也值得专门说一句。当你按行业、地区、规模等维度做亚组回归时，文本分类结果在不同亚组里的质量可能是不同的。比如A行业的投诉文本措辞规范，模型分类准确率高；B行业的文本口语化严重，分类准确率低。如果在亚组比较里直接用这些分类结果，组间差异可能有一部分来自分类质量的差异，而不是真实效应差异。做亚组分析前，至少对各组抽样复核一下分类准确率，确保组间质量可接受，否则结论的稳健性会被质疑。

回到我自己处理投诉数据的那个项目。三百条、一千条、三千条，文本规模一层层加码，我用catllm把所有投诉先分成四类，又做了二次主题归纳，最后把类别变量接进reghdfe跑了一版关于服务质量与复购关系的面板模型。整个流程没有离开Stata，代码全部留在同一个do文件里。我个人最想分享的一个小技巧是：每次调用前把文本里的换行符替换成空格，并让模型只做一件事——分类就只输出类别，提炼关键词就只输出关键词。比起复杂的提示词技巧，这一点对输出稳定性的改善最明显。catllm不是万能的，它不会替你设计研究问题，也不会替你检验结论，但只要你能把任务定义清楚，它确实能让“文本数据进入计量模型”这件事变得不再令人头疼。