先别急着写代码。很多人学Python最痛苦的一点就是语法看了不少但始终不知道能拿它做什么。这次我带你写一个真正能用的AI小工具全程用Python不涉及训练模型这类复杂操作只要照着步骤走就能在命令行里跑起来。这个工具叫AI文案分析助手你把一段文字丢给它它会自动给出情感倾向正面、负面还是中性、提取出这句话里的关键词、再浓缩成一句摘要。无论是分析评论区、整理用户反馈还是想快速判断一篇文章的态度它都能帮上忙。这篇适合谁适合已经学过Python基本语法、但还从未把AI能力接进自己程序里的初学者。如果你基础偏弱也没关系代码我会逐行解释照着敲一遍也能跑通。整个过程分四块先想清楚程序要做什么再配置Python环境然后实现在线AI模式最后给一个不联网也能运行的离线保底方案顺便把调试和排错方法演示一遍。整篇看下来你对“AI小工具是怎么从零写出来的”会有一个清晰的画面。1. 先想清楚再动手这个AI小工具到底要做什么1.1 新手做AI项目最容易被忽略的是需求拆解刚接触Python和AI的新手最常见的路径是找到一个现成的demo复制、运行、看到输出然后……没有然后。因为demo是别人想清楚之后写出来的你只是按了一下运行键。真正要自己动手做一个工具第一步不是写代码而是把“模糊想法”变成“明确需求”。我给自己定了一个非常小的需求做一个命令行程序用户输入一段中文文字程序输出三个结果——情感倾向、关键词列表、一句话摘要。为什么选这个需求它足够小不牵扯训练模型和调参它足够实用不管是分析商品评价、监控评论区还是整理用户反馈都会用到它还能覆盖一次完整AI开发的核心链路调用接口、构造输入、解析输出、处理异常。新手把这些流程完整走一遍以后再写别的AI小工具其实就是套同一个壳。顺便说一句新手很容易在“做什么”上面摇摆今天想做聊天机器人明天想做图片识别最后哪个都没做完。建议先克制住挑一个两三小时能写完的项目。第一次成功跑通带来的正反馈比项目本身有多大用处重要得多。1.2 在线大模型接口和离线本地方案怎么选确定好需求之后紧接着就是技术选型。这个工具的“AI核心”有两类实现路径方案效果联网要求成本配置难度在线大模型接口理解力强能处理复杂语义需要联网小额或免费额度低申请密钥即可调用离线轻量库只能做基础文本分析不需要免费低安装依赖即可在线模式的优势很明显模型的理解能力强一句话里隐含的态度、转折、反讽都能识别出来而且不需要我们自己实现算法。离线模式的优势是稳定可控不依赖网络、不消耗接口额度、隐私性好但效果相对粗糙遇到复杂表达容易判断不准。我给这个工具的定位是“主在线、副离线”。也就是说在线大模型作为主力离线轻量库作为兜底防止没有网络或者接口额度用尽的情况。两个方案都写出来还有一个好处可以对比学习同一个需求用不同技术路线实现起来差别在哪里。这种对比带来的理解深度是只看教程很难获得的。1.3 画清楚功能清单和验收标准需求拆完之后把功能清单写清楚输入一段中文文本建议长度在20字以上太短的文本信息量不够模型也不好判断输出情感标签positive / negative / neutral、把握度模型自评的置信程度、Top 5关键词、不超过30字的一句话摘要交互方式命令行工具支持直接输入文本也支持从文件读取内容验收标准也很简单输入“这家咖啡店氛围很好店员热情咖啡口感醇厚价格也合理我下次还会再来。”程序能输出合理的正面评价结果关键词和摘要都能贴合原文。这个验收标准非常重要。新手写代码容易陷入“无限优化”的状态总觉得还能再改改却说不清什么叫“完成”。有验收标准你就知道自己跑到哪一步可以停下来下一步该往哪个方向扩展。2. 5分钟搭好Python环境和项目骨架2.1 安装Python和代码编辑器别在这一步纠结Python 3.9以上的版本都够用建议直接选择最新稳定版。去Python官方网站下载安装包安装时勾选“Add Python to PATH”其他选项按默认来。装完在终端里执行python --version能输出版本号就说明装好了。编辑器选一个自己用着顺手的免费编辑器就行带语法高亮和代码补全的最好。如果你之前完全没用过编辑器也不用纠结太久先装一个常见的免费编辑器打开项目目录开始写代码。编辑器只是工具写代码本身才是核心等用熟了再换也不迟。2.2 虚拟环境给项目单独开一个房间项目到手第一件事是创建一个虚拟环境。虚拟环境相当于给这个项目单独开一个房间你在里面安装的任何依赖都不会影响系统全局其他项目的依赖也不同担心被覆盖。在终端里执行以下命令mkdir ai-text-assistant cd ai-text-assistant python -m venv venv目录创建好之后需要激活虚拟环境。Windows PowerShell里激活命令是venv\Scripts\Activate.ps1macOS或Linux是source venv/bin/activate。激活成功之后终端提示符前面会出现(venv)标记这时你运行Python、安装库都会在这个虚拟环境里进行。有个小坑提醒一下Windows PowerShell默认可能会禁止执行脚本如果激活时报错可以在PowerShell里运行一次Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser之后再激活就正常了。这台机器只针对当前用户放开安全性不会有问题。2.3 安装项目依赖接下来安装依赖。这个工具用到的第三方库不多pip install requests jieba snownlp python-dotenv每个库干什么的先心里有数requestsPython里最常用的HTTP请求库用来调用在线大模型接口jieba中文分词库离线模式提取关键词要用snownlp轻量级中文情感分析库离线模式判断情感倾向要用python-dotenv读取.env文件里的配置用来管理密钥避免把密钥硬编码进代码装完之后可以用pip list验证看到这几个包出现在列表里环境就准备好了。2.4 项目文件结构提前分好工项目里文件比较多如果全部堆在同一个文件里后面改起来会很痛苦。我习惯从一开始就把代码按职责拆开ai-text-assistant/ ├── main.py # 程序入口负责和用户交互 ├── ai_analyze.py # 在线大模型分析逻辑 ├── local_analyze.py # 离线本地分析逻辑 ├── config.py # 统一读取配置和选择分析模式 ├── .env # 存放密钥和配置项 └── requirements.txt # 依赖清单这个结构不复杂但能让你一眼看清每个文件负责什么。以后想加功能知道该改哪个文件出问题了也知道该去哪个文件排查。3. 在线AI模式让大模型帮你分析文本3.1 申请密钥和准备接口信息在线模式的原理很简单你本地写一个请求发给远端的大模型服务拿到返回结果之后解析出来。整个过程不需要你理解模型内部怎么运作只需要按照接口规则把请求发对。你需要准备三样东西一个能提供大模型接口的服务商账号、一个API Key、以及对应的接口地址和模型名称。现在很多平台都提供免费额度学习阶段完全够用不用急着花钱。把密钥和配置写进.env文件API_KEY你的密钥 BASE_URLhttps://api.your-provider.com/v1 MODEL_NAMEyour-model-name注意.env文件不要提交到公开的代码仓库里。密钥一旦泄露别人就能用你的额度甚至产生额外费用。用环境变量管理密钥是安全底线也是职业习惯。3.2 封装一个通用的聊天请求函数在线大模型接口的调用方式本质上就是一个HTTP POST请求。我们先用requests写一个通用的请求函数import os import requests from dotenv import load_dotenv load_dotenv() API_KEY os.getenv(API_KEY) BASE_URL os.getenv(BASE_URL, https://api.your-provider.com/v1) MODEL_NAME os.getenv(MODEL_NAME, your-model-name) def chat_completion(messages, temperature0.3): url f{BASE_URL}/chat/completions headers { Authorization: fBearer {API_KEY}, Content-Type: application/json, } payload { model: MODEL_NAME, messages: messages, temperature: temperature, } resp requests.post(url, headersheaders, jsonpayload, timeout30) resp.raise_for_status() data resp.json() return data[choices][0][message][content]几个关键点说一下。Authorization请求头里放的是密钥这是服务商识别你身份的凭证timeout30防止网络卡住时程序无响应resp.raise_for_status()会在请求状态码不是2xx时直接抛异常省去手动判断的麻烦。这里有个新手很容易踩的坑大模型接口的返回最外层是一个HTTP响应的JSON结构里面有choices、usage等字段而模型真正回复的内容在data[choices][0][message][content]。这点我们等下解析时还会碰到代码写多了自然就熟悉了。3.3 设计Prompt让模型按固定JSON格式返回请求函数写完接下来是整个在线模式最核心的部分Prompt设计。很多新手以为Prompt就是随便写一句话让AI做件事但真正做工程化工具Prompt必须严谨因为它直接影响程序能否正确解析结果。我设计的系统提示词长这样ANALYZE_SYSTEM_PROMPT 你是一个文本分析助手。请分析用户输入的中文文本并只输出一个JSON对象不要输出任何额外文字不要使用代码块标记。 JSON格式如下 { sentiment: positive/negative/neutral, confidence: 0.0~1.0, keywords: [关键词1, 关键词2], summary: 不超过30字的一句话摘要 } 你在提示词里告诉模型“只输出JSON”模型大概率会遵守但有时候还是会在JSON前后加一句解释或者用代码块把它包起来。所以代码里必须做容错解析import json import re def parse_json(raw): raw raw.strip() if raw.startswith(): raw re.sub(r^[a-zA-Z]*\s*|\s*$, , raw) return json.loads(raw)这个函数先把代码块标记剥掉再交给json库解析。别小看这几行实际用下来模型偶尔不守规矩的时候这个函数能帮你避免很多崩溃。3.4 在线分析的完整封装把请求函数和解析函数组合起来就得到在线分析函数def analyze_with_llm(text): messages [ {role: system, content: ANALYZE_SYSTEM_PROMPT}, {role: user, content: f请分析这段文本{text}}, ] raw chat_completion(messages, temperature0.3) return parse_json(raw)这里用了temperature0.3。temperature控制生成结果的随机性数值越高越有创造力越低越稳定。分析文本、结构化输出这类任务稳定比创造性重要所以调低一点。3.5 把三大功能串进命令行主程序在线分析函数封装好之后写一个最小可用的命令行入口def main(): text input(请输入要分析的文本).strip() if not text: print(文本不能为空) return result analyze_with_llm(text) print(f情感{result.get(sentiment)}把握度 {result.get(confidence)}) print(f关键词{、.join(result.get(keywords, []))}) print(f摘要{result.get(summary)}) if __name__ __main__: main()运行时程序会先等待你输入文本然后调用大模型接口最后把情感、关键词、摘要格式化打印出来。输入前面那句咖啡店的例子理想输出大概是情感positive把握度 0.91 关键词咖啡店、氛围、店员、热情、口感 摘要顾客对咖啡店环境和服务给出好评表示还会再来。到这里在线模式已经能完整跑通了。4. 离线AI模式没网也能完成的保底方案4.1 snownlp怎么判断情感在线模式需要网络和密钥如果这两个条件都不满足你的工具就废了。所以我写了离线模式用轻量级本地库实现同样的三大功能。离线情感分析用snownlpfrom snownlp import SnowNLP def offline_sentiment(text): s SnowNLP(text) score s.sentiments rounded round(score, 2) if score 0.6: return positive, rounded if score 0.4: return negative, rounded return neutral, roundedsnownlp的sentiments属性返回一个0到1之间的值越接近1越正面越接近0越负面。我设置0.6和0.4两个阈值大于0.6判正面小于0.4判负面中间算中性。这个阈值你可以根据自己的语料调整并没有标准答案。snownlp对短文本很敏感一句话如果太短比如“还行”两个字它基本判断不了。所以离线模式下建议输入有个二三十字以上效果会稍微稳定一些。4.2 提取关键词停用词过滤加简化版TextRank离线模式没有大模型帮你“理解”文本只能靠统计规律。最朴素的思路是词频出现次数多的词重要。但高频词往往是“这”“的”“是”这类没有实际含义的词所以要先过滤停用词再统计。更进一步我用了一个简化版TextRank思路。它比纯词频好在哪里纯词频只关心“这个词出现了几次”而TextRank会考虑“这个词和哪些词一起出现”。比如一段食品评价里“口感”和“醇厚”经常一起出现那么它们就会互相加分最终筛选出来的关键词更能代表文本主题。import jieba import re from collections import defaultdict STOP_WORDS {的, 了, 是, 在, 我, 有, 就, 不, 也, 都, 很, 这, 那, 你, 它, 啊, 呀, 呢, 吧} def token_filter(text): words jieba.lcut(text) result [] for word in words: word word.strip() if len(word) 2: continue if not re.fullmatch(r[\u4e00-\u9fa5A-Za-z0-9], word): continue if word in STOP_WORDS: continue result.append(word) return result def extract_keywords(text, top_k5): words token_filter(text) if not words: return [] graph defaultdict(lambda: defaultdict(int)) for i in range(len(words) - 1): w1, w2 words[i], words[i 1] graph[w1][w2] 1 graph[w2][w1] 1 scores {word: 1.0 for word in graph} d 0.85 for _ in range(10): new_scores {} for word in scores: rank_sum 0 neighbors graph[word] total sum(neighbors.values()) for next_word, weight in neighbors.items(): rank_sum (weight / total) * scores[next_word] new_scores[word] (1 - d) d * rank_sum scores new_scores ranked sorted(scores.items(), keylambda item: item[1], reverseTrue) return [word for word, _ in ranked[:top_k]]代码里构建了一个词与相邻词的共现图然后迭代更新每个词的权重权重收敛后取Top N。这一段对新手来说可能偏算法但你把它当成一个黑盒其实问题不大给一段文本进去返回几个关键词出来。真正想深入理解能看懂最好看不懂先把代码存着后面慢慢消化也一样能用。4.3 简易抽取式摘要给句子打分摘要生成有两种思路。一种是生成式由模型重新写一句在线大模型就是这样做的。另一种是抽取式从原文里挑最重要的句子离线模式用这个思路。实现逻辑很直观把文本按句号、感叹号等切成句子然后给每个句子打分。关键词出现在哪个句子里那个句子就加分首句天然有引导作用也加一点位置权重。最后取分数最高的句子作为摘要TOP_SUMMARY_SENTENCE_MAX_LEN 50 def make_summary(text): sentences re.split(r[。!?], text) sentences [s.strip() for s in sentences if len(s.strip()) 5] if not sentences: return text[:30] keywords extract_keywords(text, top_k5) scored [] for idx, sentence in enumerate(sentences): score 0 for keyword in keywords: if keyword in sentence: score 1 if idx 0: score 0.5 scored.append((score, idx, sentence)) scored.sort(keylambda item: (-item[0], item[1])) return scored[0][2][:TOP_SUMMARY_SENTENCE_MAX_LEN]这段代码很粗糙但足够体现抽取式摘要的核心思想。想让摘要质量更高可以继续优化打分规则比如把句子长度、关键词密度加进权重甚至把句子的位置信息做成可配置的权重。我建议新手先把粗糙版跑通再一点点调不要一上来就追求完美。4.4 在线和离线双模式统一封装三个离线函数都有了接下来把在线和离线统一成一个入口。在config.py里做一个简单的模式选择import os from dotenv import load_dotenv load_dotenv() AI_MODE os.getenv(AI_MODE, online)然后在本地分析文件里把离线功能组装成和在线模式相同的返回结构def analyze_local(text): sentiment, confidence offline_sentiment(text) keywords extract_keywords(text, top_k5) summary make_summary(text) return { sentiment: sentiment, confidence: confidence, keywords: keywords, summary: summary, }为什么要求返回结构一致因为main.py只关心结果格式不关心它来自在线还是离线。在线返回什么样离线也返回什么样之前写好的打印代码就完全不用改。这种“接口统一”的思想在工程里非常重要它让不同的底层实现可以互相替换模块之间不会互相牵连。5. 从能跑到好用完整跑通记录与调优5.1 先让程序骨架能跑再验证AI能力我第一次做这类工具的时候没有一上来就接大模型接口而是先写了一个“假”的分析函数固定返回一组数据def fake_analyze(text): return { sentiment: positive, confidence: 0.95, keywords: [测试, 关键词], summary: 这是测试摘要, }用这个函数把输入、打印、格式化整条链路全部跑通确认命令行交互没毛病之后再把它替换成真实AI调用。这个习惯叫“先搭骨架再填肉”。好处是每一层都能单独验证出问题的时候能立刻判断是哪一层的问题而不是等所有代码拼起来之后对着一大坨代码干瞪眼。很多新人上来就想着一步到位结果网络请求、JSON解析、中文编码、命令行参数全部缠在一起错了半天找不到根源。先跑通骨架后面的每一步都会轻松很多。5.2 接上在线大模型验证Prompt和解析把fake_analyze换成analyze_with_llm再跑同一段输入。我第一次跑的时候模型除了JSON还输出了一堆解释文字parse_json直接抛了异常。我做了两处调整。第一处是系统提示词里加了一句“不要输出任何额外文字不要使用代码块标记”。第二处是写了容错解析函数先把代码块围栏剥掉再解析。两处下来JSON解析失败的概率大大降低。这个过程中我最大的体会是Prompt不是写一次就完事它需要针对实际输出做迭代。每一版Prompt里遗漏的边界条件都会在返回结果里变成一次报错。所以调试Prompt时一定要把模型原始返回打出来看别只盯着报错信息猜。看到原始输出你往往一眼就能发现问题是出在格式、字段名还是语义理解上。5.3 加上异常降级在线挂了也能用模型接口再稳定也有网络波动、额度用尽的时候。我后来给程序包了一层保护逻辑def safe_analyze(text): try: return analyze_with_llm(text) except Exception as exc: print(f在线分析失败降级到本地模式{exc}) return analyze_local(text)这个函数的设计思路很朴素主用在线如果任何异常发生就自动退回到离线模式保证用户仍然能拿到一个结果。对一个工具来说“大多数时候好用”和“偶尔完全不可用”之间的差距很大异常降级就是填补这个差距最简单有效的方式。5.4 让工具支持文件输入和命令行参数命令行交互适合单次测试真正要分析一批评论时一条条复制粘贴实在太痛苦。我给工具加了一个能力支持把文件路径当参数传进去程序读取文件后整体分析。import sys def read_text_from_args(): if len(sys.argv) 1: path sys.argv[1] with open(path, encodingutf-8) as f: return f.read() return None text read_text_from_args() if text is None: text input(请输入要分析的文本)注意open(path, encodingutf-8)这里的编码参数在Windows上读取中文文件如果不指定UTF-8很容易出现乱码。这个小细节能省掉你很多烦恼。5.5 把分析结果保存成文件分析完文本顺手把结果存下来这样你能积累数据后面可以做统计分析。保存格式我推荐JSON Lines每行一个JSON对象import json def save_result(text, result): with open(results.jsonl, a, encodingutf-8) as f: f.write(json.dumps({text: text, result: result}, ensure_asciiFalse) \n)ensure_asciiFalse的作用是让中文正常显示不加这个参数的话保存的中文会被转成\uXXXX形式的转义字符读起来十分头疼。有了这个保存功能每次分析的结果自动累积到一个文件里后面拿去做统计报表或者训练自己的分类器都有现成数据可用。6. 新手高频报错与排查实录6.1 网络请求报错先从三个地方查起最常见的报错是requests.exceptions.ConnectionError或者超时。遇到这种错误先不要怀疑代码逻辑按顺序查三件事第一本机网络是否正常目标接口是否可达。第二API Key有没有填错BASE_URL和MODEL_NAME是否符合服务商文档要求。第三接口返回的状态码401通常表示密钥无效429表示请求太频繁或额度超限。新手经常把网络问题当成代码问题对着函数反复看却漏掉了最基本的排查项。建议养成一个习惯先把接口返回的状态码和响应体用print打印出来很多时候问题看一眼就明白了。6.2 中文乱码问题编码统一是治本方案Windows的cmd或PowerShell里运行程序输出中文乱码很常见根因是终端默认编码和Python的UTF-8不一致。两个快速解决办法一是运行前执行chcp 65001切换终端到UTF-8代码页二是用python -X utf8 main.py启动Python强制使用UTF-8处理输入输出。写文件乱码则一般是open没指定编码统一在打开文件时加上encodingutf-8几乎不会再出现乱码。小工具开发中编码问题最消磨耐心早处理早轻松。6.3 JSON解析失败用一条提示词加一个容错函数json.JSONDecodeError也是高频报错。原因往往离不开两点模型输出带了代码块标记或是在JSON前后加了额外文字。解决办法在前面已经写了再加一条如果要彻底治本可以在系统提示词里给模型一个具体输出示例叫作few-shot。模型看过你期望的格式比只读文字描述更容易遵守。如果用了这些手段还是偶尔报错那就接受一个现实在线模型的输出天生带有随机性完全杜绝异常不现实。解法就是把异常处理写好让程序在解析失败时能自动降级到本地模式而不是直接崩溃。6.4 情感分析结果不准先看输入长度和阈值离线模式下情感判断不准通常有两个原因。一是输入太短snownlp对十几个字的短文本几乎无能为力这种情况可以提示用户加长输入。二是阈值设置不合适你可以把离线模式的0.4和0.6阈值调一调观察不同阈值在自己语料上的表现。在线模式判断不准通常不是模型能力问题而是Prompt里没有把判断标准说清楚。比如“客服回复很快”这句话既有对效率的褒义也有偏中性的客观描述如果不给模型明确的判断规则它的输出就会摇摆。在系统提示词里补充一句“当文本同时包含褒义和中性内容时以整体态度倾向为准”结果会稳定很多。6.5 快速排查速查表症状可能原因解决办法连接报错网络不通、接口地址错误检查本机网络、确认BASE_URL401/403API Key错误或权限不足检查.env配置、确认账号状态429请求频率过高或额度超限降低调用频率或切本地模式中文乱码终端编码或文件编码不统一chcp 65001、open(...encodingutf-8)JSONDecodeError模型输出格式不合法容错解析、Prompt加few-shot示例离线情感总是中性输入过短、阈值不当调阈值、增加输入文本长度提取出常见无意义词停用词表不够完整扩充停用词表排查顺序建议先看错误信息再检查调用参数最后怀疑算法逻辑。顺序反了就会在一个不可能有bug的地方反复踱步。我做完这个小工具最大的感受是AI开发并没有想象中那么神秘它就是把你脑海里的一个需求翻译成“输入—处理—输出”的代码流程再用接口或模型完成“处理”这一环。新手跑通之后可以继续把玩下去把命令行改成带输入框的桌面应用或网页小工具把单条分析改成批量处理文件把结果存进表格里生成统计报表。每次只加一个功能你对“从需求到工具”的掌控感就会强一分。最后分享一个个人习惯做这种练习时我会把每一次报错和解决过程记在一个文档里攒一段时间再看那些你反复踩的坑其实就是你进步最快的地方。
