戰(zhàn)：從文本生成到Word導(dǎo)出的完整教程)
之前在做一個(gè)內(nèi)部知識(shí)整理工具時(shí)想把 Grok 生成的回答自動(dòng)轉(zhuǎn)成結(jié)構(gòu)化文檔并導(dǎo)出到 Word結(jié)果卡在 API 參數(shù)、模型名和文本格式處理上網(wǎng)上的資料又比較零散。最近看到 Grok 4.6 相關(guān)話(huà)題熱度很高結(jié)合我自己調(diào)試的經(jīng)驗(yàn)整理一篇完整的實(shí)戰(zhàn)教程從 API 接入、文本生成到 Word 導(dǎo)出把整個(gè)過(guò)程完整走一遍。如果你是第一次接觸 Grok或者已經(jīng)在用但想把它接進(jìn)自己的腳本、做點(diǎn)自動(dòng)化工具這篇文章都適用。本文會(huì)以 Grok 4.6 作為背景重點(diǎn)演示一套可復(fù)制的工程化方案先講清楚 Grok 的核心概念和適用場(chǎng)景再搭建 Python 環(huán)境接著調(diào)用 API 生成文本最后把生成結(jié)果保存為 Markdown 并轉(zhuǎn)成 Word 文檔。文末還會(huì)整理高頻報(bào)錯(cuò)的排查思路以及我在實(shí)際項(xiàng)目里總結(jié)的幾條最佳實(shí)踐盡量做到新手能跟著做有經(jīng)驗(yàn)的人也能直接翻到對(duì)應(yīng)章節(jié)排錯(cuò)。1. Grok 4.6 到底是什么它解決什么問(wèn)題在寫(xiě)代碼之前先把概念理清楚。Grok 是 xAI 推出的對(duì)話(huà)式大模型產(chǎn)品主打自然語(yǔ)言理解、代碼生成、邏輯推理和多模態(tài)內(nèi)容處理能力。Grok 4.6 是它的一個(gè)版本迭代按照目前大模型版本迭代的慣例這類(lèi)版本通常會(huì)在上下文理解、指令跟隨、工具調(diào)用效率等方面做優(yōu)化。對(duì)開(kāi)發(fā)者來(lái)說(shuō)Grok 更重要的身份是一個(gè)可以編程調(diào)用的服務(wù)通過(guò)官方提供的 API我們可以把它的能力嵌入到自己的應(yīng)用、腳本、自動(dòng)化流程里。換句話(huà)說(shuō)Grok 不只存在于聊天網(wǎng)頁(yè)里它還可以成為你后端服務(wù)的一個(gè)“AI 引擎”。1.1 Grok 4.6 的核心定位從使用角度看Grok 4.6 大致可以承擔(dān)以下幾類(lèi)任務(wù)文本生成與潤(rùn)色比如寫(xiě)技術(shù)文檔、改郵件、生成會(huì)議紀(jì)要。代碼理解與編寫(xiě)比如解釋一段復(fù)雜邏輯、根據(jù)需求生成函數(shù)、補(bǔ)充單元測(cè)試。內(nèi)容總結(jié)與信息抽取比如從長(zhǎng)文本里提取關(guān)鍵信息或者把一段對(duì)話(huà)整理成結(jié)構(gòu)化列表。工具鏈集成通過(guò) API 把模型能力接入到現(xiàn)有軟件中形成自動(dòng)化工作流。需要說(shuō)明的是我不打算在本文里給 Grok 4.6 寫(xiě)一堆“性能跑分”或“參數(shù)規(guī)?！敝?lèi)的數(shù)字因?yàn)檫@些數(shù)據(jù)要以官方發(fā)布為準(zhǔn)而且更新很快。本文的核心是操作路徑怎么把它的能力真正用起來(lái)。1.2 適合哪些人使用我把讀者分成兩類(lèi)第一類(lèi)是入門(mén)者。你可能只是想在本地寫(xiě)個(gè) Python 腳本讓 Grok 幫你生成文章、生成代碼片段或者把一段文本整理成規(guī)范的 Word 文檔。這篇文章會(huì)把這套流程拆得很細(xì)。第二類(lèi)是后端開(kāi)發(fā)者。你需要在項(xiàng)目中接入 AI 能力或者想做一個(gè)內(nèi)部工具讓同事通過(guò)命令行、Web 表單等方式使用 Grok。這篇文章里的工程化建議和錯(cuò)誤排查部分會(huì)更有用。1.3 本文會(huì)帶大家完成什么讀完并且跟著做完你會(huì)得到幾個(gè)明確的結(jié)果一個(gè)能獨(dú)立運(yùn)行的 Python 腳本輸入提示詞后調(diào)用 Grok API 拿到生成結(jié)果。一個(gè)把生成內(nèi)容自動(dòng)保存為 Markdown 文件、再轉(zhuǎn)成 Word 文檔的完整流程。一套針對(duì)常見(jiàn)報(bào)錯(cuò)的處理方案比如認(rèn)證失敗、模型名寫(xiě)錯(cuò)、請(qǐng)求超時(shí)、輸出格式異常等。這個(gè)流程雖然示例味比較重但改一改就能用在真實(shí)項(xiàng)目里比如做成 Flask 接口、定時(shí)任務(wù)或者內(nèi)部知識(shí)管理工具。2. 環(huán)境準(zhǔn)備與版本說(shuō)明開(kāi)始寫(xiě)代碼前先把環(huán)境準(zhǔn)備好。版本相關(guān)的內(nèi)容我會(huì)盡量寫(xiě)得通用因?yàn)?Grok API 的演進(jìn)速度比較快你手頭的版本可能和我寫(xiě)文章時(shí)已經(jīng)不一樣。2.1 運(yùn)行環(huán)境本文示例使用 Python 3建議使用 3.9 及以上版本。為什么推薦 3.9 以上因?yàn)楹竺娴念?lèi)型標(biāo)注、異常處理機(jī)制在更早版本里表現(xiàn)不一致而且新版 openai SDK 對(duì) Python 版本也有最低要求。操作系統(tǒng)方面Windows、macOS、Linux 都可以本文示例代碼沒(méi)有依賴(lài)某個(gè)特定平臺(tái)的系統(tǒng)調(diào)用。如果你在 Windows 上運(yùn)行命令提示符或 PowerShell 都可以如果是在 Linux 服務(wù)器上跑建議使用虛擬環(huán)境隔離依賴(lài)。2.2 安裝 Python 依賴(lài)我們?cè)谑纠袝?huì)用到兩個(gè)核心庫(kù)openai官方 SDKGrok API 兼容 OpenAI 的消息格式所以可以直接用這個(gè)庫(kù)調(diào)用。python-docx用于生成 Word 文檔。安裝命令如下pip install openai python-docx如果你使用虛擬環(huán)境可以先創(chuàng)建并激活環(huán)境python -m venv venv source venv/bin/activate # Windows 上使用 venv\Scripts\activate這里要特別提醒一句openai 庫(kù)的版本更新比較快不同版本之間部分參數(shù)名和默認(rèn)行為可能有差異。如果你發(fā)現(xiàn)某些參數(shù)報(bào)錯(cuò)可以先用pip show openai查看當(dāng)前版本再對(duì)照官方文檔調(diào)整。本文的代碼以常見(jiàn)的 1.x 版本為示例。2.3 獲取 API Key調(diào)用 Grok API 需要 API Key。通常的操作路徑是登錄 xAI 官方平臺(tái)在開(kāi)發(fā)者控制臺(tái)或 API 設(shè)置頁(yè)面創(chuàng)建 Key。創(chuàng)建后請(qǐng)立刻復(fù)制保存因?yàn)橛行┢脚_(tái)只在創(chuàng)建時(shí)顯示一次完整 Key。獲取到 Key 后建議不要直接硬編碼在代碼里而是通過(guò)環(huán)境變量讀取export XAI_API_KEY你的API Key在本地調(diào)試時(shí)也可以寫(xiě)進(jìn).env文件然后用 python-dotenv 加載。本文為了保持示例簡(jiǎn)潔直接在代碼里使用環(huán)境變量讀取方式。3. Grok API 接入方式與核心概念Grok API 的接入方式對(duì)大多數(shù)開(kāi)發(fā)者來(lái)說(shuō)并不陌生因?yàn)樗捎昧伺c OpenAI 兼容的 Chat Completions 消息結(jié)構(gòu)。也就是說(shuō)如果你之前寫(xiě)過(guò)調(diào)用 GPT 系列模型的代碼切換到 Grok 的成本很低。3.1 OpenAI 兼容接口“兼容”體現(xiàn)在兩個(gè)層面請(qǐng)求結(jié)構(gòu)一致都是傳一個(gè) messages 數(shù)組每個(gè)元素有 role 和 content。響應(yīng)結(jié)構(gòu)一致返回值里有 choices 數(shù)組里面放著模型生成的文本。這種設(shè)計(jì)對(duì)開(kāi)發(fā)者很友好因?yàn)椴恍枰獮槊總€(gè)模型單獨(dú)寫(xiě)一套調(diào)用代碼只需要換 base_url、api_key 和 model 參數(shù)。需要注意的是API 地址要根據(jù)官方文檔填寫(xiě)。不同時(shí)期、不同服務(wù)商的接入地址可能不同本文示例使用https://api.x.ai/v1作為演示實(shí)際使用時(shí)請(qǐng)以你獲得的官方文檔為準(zhǔn)。3.2 最小可運(yùn)行示例先來(lái)看一個(gè)最簡(jiǎn)單的調(diào)用示例。創(chuàng)建一個(gè)quick_start.py文件# 文件路徑quick_start.py import os from openai import OpenAI client OpenAI( api_keyos.environ.get(XAI_API_KEY), base_urlhttps://api.x.ai/v1, ) response client.chat.completions.create( modelgrok-4.6, messages[ { role: system, content: 你是一個(gè)技術(shù)寫(xiě)作助手擅長(zhǎng)用清晰的語(yǔ)言解釋復(fù)雜概念。, }, { role: user, content: 請(qǐng)用三句話(huà)介紹什么是 API。, }, ], temperature0.7, ) print(response.choices[0].message.content)運(yùn)行方式python quick_start.py這段代碼干了幾件事創(chuàng)建 OpenAI 客戶(hù)端并把 base_url 指向 Grok 的接口地址。通過(guò)chat.completions.create發(fā)送一次對(duì)話(huà)請(qǐng)求。打印模型返回的第一條結(jié)果。如果你看到控制臺(tái)輸出了完整的三句話(huà)說(shuō)明 API 接入已經(jīng)成功。3.3 參數(shù)說(shuō)明上面的代碼里有幾個(gè)參數(shù)需要重點(diǎn)理解model模型標(biāo)識(shí)。不同時(shí)期可用的模型名可能不同示例中的grok-4.6需要根據(jù)官方文檔確認(rèn)如果提示模型不存在通常就是這個(gè)參數(shù)寫(xiě)錯(cuò)了。messages對(duì)話(huà)消息列表。系統(tǒng)消息用于設(shè)定模型角色用戶(hù)消息是實(shí)際輸入還可以追加助手消息實(shí)現(xiàn)多輪對(duì)話(huà)。temperature采樣溫度控制輸出的隨機(jī)性。值越低輸出越穩(wěn)定值越高越有創(chuàng)造性。寫(xiě)代碼類(lèi)任務(wù)建議 0.2 到 0.4寫(xiě)文案類(lèi)任務(wù)可以調(diào)到 0.7 到 0.9。很多初學(xué)者容易忽略的一點(diǎn)是直接修改代碼里的 messages 長(zhǎng)度可能不會(huì)保留歷史對(duì)話(huà)。每次調(diào)用 API 都是無(wú)狀態(tài)的要想實(shí)現(xiàn)多輪對(duì)話(huà)必須把之前的消息一并傳過(guò)去。4. 實(shí)戰(zhàn)用 Grok 4.6 構(gòu)建文本生成工具概念部分講完了下面進(jìn)入實(shí)戰(zhàn)。這個(gè)章節(jié)的目標(biāo)是完成一個(gè)相對(duì)完整的工具輸入主題調(diào)用 Grok 生成結(jié)構(gòu)化文本保存為 Markdown再導(dǎo)出為 Word 文檔。這個(gè)流程正好對(duì)應(yīng)很多人在實(shí)際需求里遇到的“怎么把 Grok 生成的文本加入 Word”。4.1 設(shè)計(jì)思路在寫(xiě)代碼之前先想清楚工具要做什么讀取用戶(hù)輸入的主題。調(diào)用 Grok API生成一篇帶標(biāo)題和段落結(jié)構(gòu)的文章。把生成結(jié)果保存成.md文件。用 python-docx 把 Markdown 文本轉(zhuǎn)成.docx文件。整體流程拆成三步對(duì)應(yīng)三個(gè)函數(shù)生成文本、保存 Markdown、轉(zhuǎn)換 Word。這樣設(shè)計(jì)的好處是每個(gè)函數(shù)只做一件事后續(xù)想改成 Web 接口或者把輸出從 Word 換成 PDF改動(dòng)都會(huì)很小。4.2 創(chuàng)建項(xiàng)目結(jié)構(gòu)我建議按下面的結(jié)構(gòu)組織文件grok-word-tool/ ├── venv/ # 虛擬環(huán)境 ├── main.py # 入口腳本 ├── grok_client.py # Grok API 調(diào)用封裝 └── output/ # 生成結(jié)果保存目錄grok_client.py負(fù)責(zé)和 API 打交道m(xù)ain.py負(fù)責(zé)流程編排。先把輸出目錄建好mkdir output4.3 編寫(xiě)核心代碼先寫(xiě)grok_client.py# 文件路徑grok_client.py import os from openai import OpenAI class GrokClient: def __init__(self): self.client OpenAI( api_keyos.environ.get(XAI_API_KEY), base_urlhttps://api.x.ai/v1, ) def generate_article(self, topic: str, max_words: int 800) - str: prompt ( f請(qǐng)圍繞「{topic}」寫(xiě)一篇結(jié)構(gòu)清晰的技術(shù)文章。\n f要求\n f1. 包含 2 到 4 個(gè)二級(jí)標(biāo)題\n f2. 每個(gè)段落內(nèi)容具體不要空泛\n f3. 正文控制在 {max_words} 字左右\n f4. 使用 Markdown 格式輸出。 ) response self.client.chat.completions.create( modelgrok-4.6, messages[ { role: system, content: 你是一個(gè)中文技術(shù)文章寫(xiě)作專(zhuān)家。, }, { role: user, content: prompt, }, ], temperature0.6, ) return response.choices[0].message.content這個(gè)類(lèi)里面做了兩件事初始化客戶(hù)端封裝文章生成方法。在生成提示詞時(shí)我把主題、字?jǐn)?shù)、格式要求都寫(xiě)進(jìn)去了這是為了讓 Grok 輸出更可控。接下來(lái)寫(xiě)main.py# 文件路徑main.py import os from grok_client import GrokClient def save_markdown(content: str, file_path: str) - None: with open(file_path, w, encodingutf-8) as f: f.write(content) print(fMarkdown 文件已保存{file_path}) def main(): topic input(請(qǐng)輸入文章主題).strip() if not topic: print(主題不能為空) return client GrokClient() content client.generate_article(topic) os.makedirs(output, exist_okTrue) md_path os.path.join(output, article.md) save_markdown(content, md_path) if __name__ __main__: main()運(yùn)行一下試試python main.py輸入一個(gè)主題例如“Python 裝飾器入門(mén)”過(guò)幾秒后打開(kāi)output/article.md應(yīng)該能看到一篇 Markdown 格式的文章。4.4 把 Grok 生成的文本加入 Word現(xiàn)在到了很多人問(wèn)的問(wèn)題怎么把 Grok 生成的文本轉(zhuǎn)成 Word。最簡(jiǎn)單的思路是直接讀取 Markdown 文本按行解析標(biāo)題和普通段落然后用 python-docx 寫(xiě)入 Word 文檔。這里要說(shuō)明一下python-docx 不原生支持 Markdown 渲染所以我們需要自己做簡(jiǎn)單解析。示例代碼只處理三種情況一級(jí)標(biāo)題、二級(jí)標(biāo)題、普通段落。對(duì)于其他 Markdown 語(yǔ)法比如列表、代碼塊你可以根據(jù)實(shí)際需求擴(kuò)展。在main.py中新增一個(gè)函數(shù)# 文件路徑main.py from docx import Document from docx.shared import Pt def markdown_to_word(md_path: str, docx_path: str) - None: doc Document() with open(md_path, r, encodingutf-8) as f: lines f.readlines() for line in lines: line line.strip() if not line: continue if line.startswith(## ): heading doc.add_heading(level1) run heading.add_run(line.replace(## , )) run.font.size Pt(18) elif line.startswith(### ): heading doc.add_heading(level2) run heading.add_run(line.replace(### , )) run.font.size Pt(15) else: doc.add_paragraph(line) doc.save(docx_path) print(fWord 文檔已保存{docx_path})然后在main()里調(diào)用def main(): topic input(請(qǐng)輸入文章主題).strip() if not topic: print(主題不能為空) return client GrokClient() content client.generate_article(topic) os.makedirs(output, exist_okTrue) md_path os.path.join(output, article.md) save_markdown(content, md_path) docx_path os.path.join(output, article.docx) markdown_to_word(md_path, docx_path)這個(gè)轉(zhuǎn)換函數(shù)的基本邏輯是遍歷 Markdown 的每一行判斷前綴。如果是##就在 Word 中插入一級(jí)標(biāo)題如果是###插入二級(jí)標(biāo)題否則插入普通段落。4.5 運(yùn)行與驗(yàn)證完整跑一遍python main.py正常情況下的輸出類(lèi)似請(qǐng)輸入文章主題Python 裝飾器入門(mén) Markdown 文件已保存output/article.md Word 文檔已保存output/article.docx打開(kāi)output/article.docx你會(huì)看到結(jié)構(gòu)和 Markdown 文件基本對(duì)應(yīng)標(biāo)題是標(biāo)題樣式段落是正文。到這里一條“Grok 生成文本 → 保存 Markdown → 導(dǎo)出 Word”的自動(dòng)化鏈路就打通了。如果你想把生成的文本加入 Word 的指定位置比如在文檔開(kāi)頭插入封面標(biāo)題或者把不同章節(jié)寫(xiě)到不同段落只需要在markdown_to_word中增加對(duì)應(yīng)邏輯即可。5. 常見(jiàn)問(wèn)題與排查思路實(shí)際使用中很少有人一次就能跑通。下面我把常見(jiàn)問(wèn)題整理成一張表格再逐個(gè)展開(kāi)說(shuō)。問(wèn)題現(xiàn)象常見(jiàn)原因解決思路401 認(rèn)證失敗API Key 無(wú)效或未正確設(shè)置檢查環(huán)境變量和 Key 是否復(fù)制完整404 模型不存在model 參數(shù)寫(xiě)錯(cuò)到官方文檔確認(rèn)當(dāng)前模型標(biāo)識(shí)429 請(qǐng)求過(guò)多觸發(fā)限流增加重試策略降低請(qǐng)求頻率請(qǐng)求超時(shí)網(wǎng)絡(luò)問(wèn)題或響應(yīng)時(shí)間過(guò)長(zhǎng)設(shè)置合理的超時(shí)時(shí)間和重試機(jī)制輸出內(nèi)容為 null內(nèi)容被安全策略攔截或參數(shù)錯(cuò)誤檢查提示詞換一種表達(dá)方式生成的 Word 格式不對(duì)Markdown 解析不完整增強(qiáng)解析邏輯處理列表和代碼塊5.1 認(rèn)證與權(quán)限問(wèn)題如果你遇到AuthenticationError首先檢查環(huán)境變量是否真的設(shè)置成功了。在終端里輸入echo $XAI_API_KEY如果輸出為空說(shuō)明環(huán)境變量沒(méi)設(shè)置或者終端會(huì)話(huà)沒(méi)有重新加載。如果輸出正常再確認(rèn) Key 是否復(fù)制完整很多 Key 末尾多一個(gè)空格都會(huì)導(dǎo)致認(rèn)證失敗。另外要注意不要把 Key 提交到 Git 倉(cāng)庫(kù)。建議在.gitignore中加入.env文件或者用密鑰管理服務(wù)保存敏感信息。5.2 請(qǐng)求超時(shí)與限流請(qǐng)求超時(shí)是調(diào)用大模型 API 時(shí)最常見(jiàn)的網(wǎng)絡(luò)類(lèi)問(wèn)題。原因主要有兩類(lèi)一是本地網(wǎng)絡(luò)到 API 服務(wù)之間的鏈路不穩(wěn)定二是生成內(nèi)容較長(zhǎng)導(dǎo)致響應(yīng)時(shí)間超過(guò)默認(rèn)超時(shí)設(shè)置。處理方式是在創(chuàng)建客戶(hù)端時(shí)增加超時(shí)參數(shù)client OpenAI( api_keyos.environ.get(XAI_API_KEY), base_urlhttps://api.x.ai/v1, timeout120.0, )遇到限流時(shí)不要死循環(huán)重試應(yīng)該用指數(shù)退避策略第一次等待 1 秒第二次等待 2 秒第三次等待 4 秒逐漸加大間隔。這樣既不會(huì)把自己本地請(qǐng)求堵死也能減少對(duì)服務(wù)端的壓力。5.3 輸出解析問(wèn)題有時(shí)候 API 調(diào)用成功了但拿到的message.content是None。這通常有兩種情況一是模型返回了內(nèi)容審核拒絕結(jié)果二是流式輸出模式下沒(méi)有正確讀取內(nèi)容。在非流式模式下建議在解析前先做一次判斷message response.choices[0].message content message.content or if not content: print(模型沒(méi)有返回內(nèi)容請(qǐng)檢查提示詞是否觸發(fā)了安全過(guò)濾)另外如果模型在輸出中使用了 Markdown 表格、代碼塊等復(fù)雜結(jié)構(gòu)你的 Word 轉(zhuǎn)換工具不一定能正確處理。這時(shí)可以在提示詞里明確要求“不要輸出表格不要輸出圍欄代碼塊”減少解析負(fù)擔(dān)。5.4 排查清單當(dāng)你遇到問(wèn)題但不知道從哪里下手時(shí)按下面的順序排查確認(rèn) API Key 有效并且環(huán)境變量能讀到。確認(rèn)模型名與官方文檔一致。用最簡(jiǎn)單的quick_start.py測(cè)試排除業(yè)務(wù)代碼干擾。查看完整報(bào)錯(cuò)堆棧區(qū)分是網(wǎng)絡(luò)錯(cuò)誤、認(rèn)證錯(cuò)誤還是參數(shù)錯(cuò)誤。在官方文檔或社區(qū)搜索報(bào)錯(cuò)信息。大多數(shù)問(wèn)題都出在模型名和環(huán)境變量上先把這兩個(gè)固定住能解決一半以上的故障。6. 最佳實(shí)踐與工程建議代碼能跑通只是第一步。如果要做成穩(wěn)定可用的工程還需要考慮提示詞設(shè)計(jì)、錯(cuò)誤處理、成本控制和安全合規(guī)等幾個(gè)方面。6.1 提示詞設(shè)計(jì)同樣一個(gè)模型提示詞寫(xiě)得好不好輸出質(zhì)量可能差很多。我一般會(huì)把提示詞拆成三部分角色設(shè)定告訴模型它是什么角色。任務(wù)描述告訴模型要完成什么任務(wù)。輸出約束告訴模型格式要求、字?jǐn)?shù)要求、內(nèi)容邊界。例如prompt ( 你是一名資深 Python 工程師。\n 請(qǐng)為下面的需求編寫(xiě)一段代碼并解釋關(guān)鍵點(diǎn)\n f需求{requirement}\n 要求代碼必須完整可運(yùn)行解釋部分不超過(guò) 200 字。 )在工程化場(chǎng)景中建議把提示詞模板抽成單獨(dú)的配置文件或模板文件方便業(yè)務(wù)人員直接修改不需要改代碼。6.2 錯(cuò)誤處理與重試任何依賴(lài)外部 API 的程序都必須假設(shè)網(wǎng)絡(luò)和上游服務(wù)不可靠。我在實(shí)際代碼中至少會(huì)做三層處理捕獲網(wǎng)絡(luò)異常并記錄日志。對(duì) 429、500、503 這類(lèi)錯(cuò)誤做指數(shù)退避重試。多次重試仍失敗時(shí)返回友好的錯(cuò)誤信息而不是直接把堆棧拋給用戶(hù)。下面是一個(gè)簡(jiǎn)單的重試示例import time from openai import OpenAI client OpenAI(api_keyyour-key, base_urlhttps://api.x.ai/v1) def call_with_retry(messages, max_retries3): for attempt in range(max_retries): try: response client.chat.completions.create( modelgrok-4.6, messagesmessages, ) return response.choices[0].message.content except Exception as e: if attempt max_retries - 1: raise wait 2 ** attempt print(f請(qǐng)求失敗{wait} 秒后重試{e}) time.sleep(wait)這個(gè)示例使用了max_retries參數(shù)限制重試次數(shù)等待時(shí)間按 1 秒、2 秒、4 秒遞增。6.3 上下文與成本控制大模型調(diào)用的費(fèi)用和輸入輸出 token 數(shù)量直接相關(guān)?？刂瞥杀镜暮诵氖侄问强刂粕舷挛拈L(zhǎng)度。在多輪對(duì)話(huà)場(chǎng)景中如果用戶(hù)一直發(fā)消息歷史記錄會(huì)越來(lái)越長(zhǎng)。常見(jiàn)做法是只保留最近幾輪消息或者用摘要代替舊消息。比如設(shè)置一個(gè)最大消息數(shù)超過(guò)后把最舊的消息壓縮成一句摘要。另外建議在生成任務(wù)中明確限制輸出長(zhǎng)度。如果你的文章只需要 800 字就在提示詞里寫(xiě)清楚避免模型輸出一大段冗余內(nèi)容。6.4 安全與合規(guī)使用 Grok API 時(shí)必須遵守官方服務(wù)條款只通過(guò)正規(guī)渠道獲取 API Key不要使用任何未經(jīng)授權(quán)的接入方式。不要嘗試讓模型生成違法、攻擊性、歧視性?xún)?nèi)容也不要使用所謂的“免審核提示詞”一類(lèi)技巧。作為開(kāi)發(fā)者尤其是后端開(kāi)發(fā)者需要對(duì)用戶(hù)通過(guò)你的工具提交的內(nèi)容做基本的安全過(guò)濾。如果這個(gè)工具面向公眾開(kāi)放建議在前后端都加入敏感內(nèi)容檢測(cè)機(jī)制避免你的應(yīng)用成為內(nèi)容風(fēng)險(xiǎn)傳播的入口。另外日志中不要記錄完整的用戶(hù)輸入和模型輸出尤其是涉及個(gè)人隱私或業(yè)務(wù)敏感數(shù)據(jù)的內(nèi)容。如果必須記錄也要做脫敏處理。6.5 可維護(hù)性當(dāng)你把“AI 能力”集成到業(yè)務(wù)系統(tǒng)后可維護(hù)性往往比炫酷的功能更重要。我建議做到以下幾點(diǎn)模型名不要散落在業(yè)務(wù)代碼里統(tǒng)一放在配置文件中。請(qǐng)求參數(shù)、提示詞模板、重試策略和業(yè)務(wù)邏輯分離。給每個(gè)調(diào)用增加唯一請(qǐng)求 ID方便在日志中追蹤問(wèn)題。在代碼注釋里寫(xiě)清楚每個(gè)參數(shù)的用途和取值范圍。這樣的代碼一開(kāi)始寫(xiě)起來(lái)略顯繁瑣但維護(hù)時(shí)會(huì)非常舒服。7. 總結(jié)與下一步學(xué)習(xí)建議這篇文章從 Grok 4.6 的概念出發(fā)完整走了一遍 API 接入、文本生成、Markdown 保存、Word 導(dǎo)出的全流程。核心收獲可以概括成三點(diǎn)第一Grok API 的接入方式不復(fù)雜熟悉 OpenAI 兼容格式后切換模型非常容易真正需要花時(shí)間的是提示詞設(shè)計(jì)和輸出解析。第二把 AI 生成內(nèi)容轉(zhuǎn)成 Word 這類(lèi)需求本質(zhì)上是一個(gè)文本處理問(wèn)題不要指望現(xiàn)成庫(kù)能一步到位先用簡(jiǎn)單解析滿(mǎn)足 80% 的需求后續(xù)再根據(jù)實(shí)際情況增強(qiáng)。第三工程化使用大模型 API重點(diǎn)在于錯(cuò)誤處理、成本控制和內(nèi)容安全。這三件事沒(méi)有做好功能再炫酷也撐不住真實(shí)業(yè)務(wù)。下一步你可以嘗試幾個(gè)方向把當(dāng)前腳本改造成 Flask 或 FastAPI 接口做成一個(gè)內(nèi)部網(wǎng)頁(yè)工具在 Markdown 轉(zhuǎn)換中支持更多語(yǔ)法比如列表、代碼塊、圖片或者給工具加上流式輸出讓用戶(hù)看到逐字生成的效果。有條件的話(huà)建議你拿著本文的示例代碼親自動(dòng)手跑一遍再改一改提示詞看看不同參數(shù)對(duì)生成結(jié)果的影響。只有自己調(diào)過(guò)一遍參數(shù)踩過(guò)幾個(gè)坑才真正算是把這套流程用熟了。如果本文對(duì)你有幫助可以先收藏備用后面用到的時(shí)候直接照著操作。 Grok 4.6 API實(shí)戰(zhàn)：從文本生成到Word導(dǎo)出的完整教程
之前在做一個(gè)內(nèi)部知識(shí)整理工具時(shí)想把 Grok 生成的回答自動(dòng)轉(zhuǎn)成結(jié)構(gòu)化文檔并導(dǎo)出到 Word結(jié)果卡在 API 參數(shù)、模型名和文本格式處理上網(wǎng)上的資料又比較零散。最近看到 Grok 4.6 相關(guān)話(huà)題熱度很高結(jié)合我自己調(diào)試的經(jīng)驗(yàn)整理一篇完整的實(shí)戰(zhàn)教程從 API 接入、文本生成到 Word 導(dǎo)出把整個(gè)過(guò)程完整走一遍。如果你是第一次接觸 Grok或者已經(jīng)在用但想把它接進(jìn)自己的腳本、做點(diǎn)自動(dòng)化工具這篇文章都適用。本文會(huì)以 Grok 4.6 作為背景重點(diǎn)演示一套可復(fù)制的工程化方案先講清楚 Grok 的核心概念和適用場(chǎng)景再搭建 Python 環(huán)境接著調(diào)用 API 生成文本最后把生成結(jié)果保存為 Markdown 并轉(zhuǎn)成 Word 文檔。文末還會(huì)整理高頻報(bào)錯(cuò)的排查思路以及我在實(shí)際項(xiàng)目里總結(jié)的幾條最佳實(shí)踐盡量做到新手能跟著做有經(jīng)驗(yàn)的人也能直接翻到對(duì)應(yīng)章節(jié)排錯(cuò)。1. Grok 4.6 到底是什么它解決什么問(wèn)題在寫(xiě)代碼之前先把概念理清楚。Grok 是 xAI 推出的對(duì)話(huà)式大模型產(chǎn)品主打自然語(yǔ)言理解、代碼生成、邏輯推理和多模態(tài)內(nèi)容處理能力。Grok 4.6 是它的一個(gè)版本迭代按照目前大模型版本迭代的慣例這類(lèi)版本通常會(huì)在上下文理解、指令跟隨、工具調(diào)用效率等方面做優(yōu)化。對(duì)開(kāi)發(fā)者來(lái)說(shuō)Grok 更重要的身份是一個(gè)可以編程調(diào)用的服務(wù)通過(guò)官方提供的 API我們可以把它的能力嵌入到自己的應(yīng)用、腳本、自動(dòng)化流程里。換句話(huà)說(shuō)Grok 不只存在于聊天網(wǎng)頁(yè)里它還可以成為你后端服務(wù)的一個(gè)“AI 引擎”。1.1 Grok 4.6 的核心定位從使用角度看Grok 4.6 大致可以承擔(dān)以下幾類(lèi)任務(wù)文本生成與潤(rùn)色比如寫(xiě)技術(shù)文檔、改郵件、生成會(huì)議紀(jì)要。代碼理解與編寫(xiě)比如解釋一段復(fù)雜邏輯、根據(jù)需求生成函數(shù)、補(bǔ)充單元測(cè)試。內(nèi)容總結(jié)與信息抽取比如從長(zhǎng)文本里提取關(guān)鍵信息或者把一段對(duì)話(huà)整理成結(jié)構(gòu)化列表。工具鏈集成通過(guò) API 把模型能力接入到現(xiàn)有軟件中形成自動(dòng)化工作流。需要說(shuō)明的是我不打算在本文里給 Grok 4.6 寫(xiě)一堆“性能跑分”或“參數(shù)規(guī)?！敝?lèi)的數(shù)字因?yàn)檫@些數(shù)據(jù)要以官方發(fā)布為準(zhǔn)而且更新很快。本文的核心是操作路徑怎么把它的能力真正用起來(lái)。1.2 適合哪些人使用我把讀者分成兩類(lèi)第一類(lèi)是入門(mén)者。你可能只是想在本地寫(xiě)個(gè) Python 腳本讓 Grok 幫你生成文章、生成代碼片段或者把一段文本整理成規(guī)范的 Word 文檔。這篇文章會(huì)把這套流程拆得很細(xì)。第二類(lèi)是后端開(kāi)發(fā)者。你需要在項(xiàng)目中接入 AI 能力或者想做一個(gè)內(nèi)部工具讓同事通過(guò)命令行、Web 表單等方式使用 Grok。這篇文章里的工程化建議和錯(cuò)誤排查部分會(huì)更有用。1.3 本文會(huì)帶大家完成什么讀完并且跟著做完你會(huì)得到幾個(gè)明確的結(jié)果一個(gè)能獨(dú)立運(yùn)行的 Python 腳本輸入提示詞后調(diào)用 Grok API 拿到生成結(jié)果。一個(gè)把生成內(nèi)容自動(dòng)保存為 Markdown 文件、再轉(zhuǎn)成 Word 文檔的完整流程。一套針對(duì)常見(jiàn)報(bào)錯(cuò)的處理方案比如認(rèn)證失敗、模型名寫(xiě)錯(cuò)、請(qǐng)求超時(shí)、輸出格式異常等。這個(gè)流程雖然示例味比較重但改一改就能用在真實(shí)項(xiàng)目里比如做成 Flask 接口、定時(shí)任務(wù)或者內(nèi)部知識(shí)管理工具。2. 環(huán)境準(zhǔn)備與版本說(shuō)明開(kāi)始寫(xiě)代碼前先把環(huán)境準(zhǔn)備好。版本相關(guān)的內(nèi)容我會(huì)盡量寫(xiě)得通用因?yàn)?Grok API 的演進(jìn)速度比較快你手頭的版本可能和我寫(xiě)文章時(shí)已經(jīng)不一樣。2.1 運(yùn)行環(huán)境本文示例使用 Python 3建議使用 3.9 及以上版本。為什么推薦 3.9 以上因?yàn)楹竺娴念?lèi)型標(biāo)注、異常處理機(jī)制在更早版本里表現(xiàn)不一致而且新版 openai SDK 對(duì) Python 版本也有最低要求。操作系統(tǒng)方面Windows、macOS、Linux 都可以本文示例代碼沒(méi)有依賴(lài)某個(gè)特定平臺(tái)的系統(tǒng)調(diào)用。如果你在 Windows 上運(yùn)行命令提示符或 PowerShell 都可以如果是在 Linux 服務(wù)器上跑建議使用虛擬環(huán)境隔離依賴(lài)。2.2 安裝 Python 依賴(lài)我們?cè)谑纠袝?huì)用到兩個(gè)核心庫(kù)openai官方 SDKGrok API 兼容 OpenAI 的消息格式所以可以直接用這個(gè)庫(kù)調(diào)用。python-docx用于生成 Word 文檔。安裝命令如下pip install openai python-docx如果你使用虛擬環(huán)境可以先創(chuàng)建并激活環(huán)境python -m venv venv source venv/bin/activate # Windows 上使用 venv\Scripts\activate這里要特別提醒一句openai 庫(kù)的版本更新比較快不同版本之間部分參數(shù)名和默認(rèn)行為可能有差異。如果你發(fā)現(xiàn)某些參數(shù)報(bào)錯(cuò)可以先用pip show openai查看當(dāng)前版本再對(duì)照官方文檔調(diào)整。本文的代碼以常見(jiàn)的 1.x 版本為示例。2.3 獲取 API Key調(diào)用 Grok API 需要 API Key。通常的操作路徑是登錄 xAI 官方平臺(tái)在開(kāi)發(fā)者控制臺(tái)或 API 設(shè)置頁(yè)面創(chuàng)建 Key。創(chuàng)建后請(qǐng)立刻復(fù)制保存因?yàn)橛行┢脚_(tái)只在創(chuàng)建時(shí)顯示一次完整 Key。獲取到 Key 后建議不要直接硬編碼在代碼里而是通過(guò)環(huán)境變量讀取export XAI_API_KEY你的API Key在本地調(diào)試時(shí)也可以寫(xiě)進(jìn).env文件然后用 python-dotenv 加載。本文為了保持示例簡(jiǎn)潔直接在代碼里使用環(huán)境變量讀取方式。3. Grok API 接入方式與核心概念Grok API 的接入方式對(duì)大多數(shù)開(kāi)發(fā)者來(lái)說(shuō)并不陌生因?yàn)樗捎昧伺c OpenAI 兼容的 Chat Completions 消息結(jié)構(gòu)。也就是說(shuō)如果你之前寫(xiě)過(guò)調(diào)用 GPT 系列模型的代碼切換到 Grok 的成本很低。3.1 OpenAI 兼容接口“兼容”體現(xiàn)在兩個(gè)層面請(qǐng)求結(jié)構(gòu)一致都是傳一個(gè) messages 數(shù)組每個(gè)元素有 role 和 content。響應(yīng)結(jié)構(gòu)一致返回值里有 choices 數(shù)組里面放著模型生成的文本。這種設(shè)計(jì)對(duì)開(kāi)發(fā)者很友好因?yàn)椴恍枰獮槊總€(gè)模型單獨(dú)寫(xiě)一套調(diào)用代碼只需要換 base_url、api_key 和 model 參數(shù)。需要注意的是API 地址要根據(jù)官方文檔填寫(xiě)。不同時(shí)期、不同服務(wù)商的接入地址可能不同本文示例使用https://api.x.ai/v1作為演示實(shí)際使用時(shí)請(qǐng)以你獲得的官方文檔為準(zhǔn)。3.2 最小可運(yùn)行示例先來(lái)看一個(gè)最簡(jiǎn)單的調(diào)用示例。創(chuàng)建一個(gè)quick_start.py文件# 文件路徑quick_start.py import os from openai import OpenAI client OpenAI( api_keyos.environ.get(XAI_API_KEY), base_urlhttps://api.x.ai/v1, ) response client.chat.completions.create( modelgrok-4.6, messages[ { role: system, content: 你是一個(gè)技術(shù)寫(xiě)作助手擅長(zhǎng)用清晰的語(yǔ)言解釋復(fù)雜概念。, }, { role: user, content: 請(qǐng)用三句話(huà)介紹什么是 API。, }, ], temperature0.7, ) print(response.choices[0].message.content)運(yùn)行方式python quick_start.py這段代碼干了幾件事創(chuàng)建 OpenAI 客戶(hù)端并把 base_url 指向 Grok 的接口地址。通過(guò)chat.completions.create發(fā)送一次對(duì)話(huà)請(qǐng)求。打印模型返回的第一條結(jié)果。如果你看到控制臺(tái)輸出了完整的三句話(huà)說(shuō)明 API 接入已經(jīng)成功。3.3 參數(shù)說(shuō)明上面的代碼里有幾個(gè)參數(shù)需要重點(diǎn)理解model模型標(biāo)識(shí)。不同時(shí)期可用的模型名可能不同示例中的grok-4.6需要根據(jù)官方文檔確認(rèn)如果提示模型不存在通常就是這個(gè)參數(shù)寫(xiě)錯(cuò)了。messages對(duì)話(huà)消息列表。系統(tǒng)消息用于設(shè)定模型角色用戶(hù)消息是實(shí)際輸入還可以追加助手消息實(shí)現(xiàn)多輪對(duì)話(huà)。temperature采樣溫度控制輸出的隨機(jī)性。值越低輸出越穩(wěn)定值越高越有創(chuàng)造性。寫(xiě)代碼類(lèi)任務(wù)建議 0.2 到 0.4寫(xiě)文案類(lèi)任務(wù)可以調(diào)到 0.7 到 0.9。很多初學(xué)者容易忽略的一點(diǎn)是直接修改代碼里的 messages 長(zhǎng)度可能不會(huì)保留歷史對(duì)話(huà)。每次調(diào)用 API 都是無(wú)狀態(tài)的要想實(shí)現(xiàn)多輪對(duì)話(huà)必須把之前的消息一并傳過(guò)去。4. 實(shí)戰(zhàn)用 Grok 4.6 構(gòu)建文本生成工具概念部分講完了下面進(jìn)入實(shí)戰(zhàn)。這個(gè)章節(jié)的目標(biāo)是完成一個(gè)相對(duì)完整的工具輸入主題調(diào)用 Grok 生成結(jié)構(gòu)化文本保存為 Markdown再導(dǎo)出為 Word 文檔。這個(gè)流程正好對(duì)應(yīng)很多人在實(shí)際需求里遇到的“怎么把 Grok 生成的文本加入 Word”。4.1 設(shè)計(jì)思路在寫(xiě)代碼之前先想清楚工具要做什么讀取用戶(hù)輸入的主題。調(diào)用 Grok API生成一篇帶標(biāo)題和段落結(jié)構(gòu)的文章。把生成結(jié)果保存成.md文件。用 python-docx 把 Markdown 文本轉(zhuǎn)成.docx文件。整體流程拆成三步對(duì)應(yīng)三個(gè)函數(shù)生成文本、保存 Markdown、轉(zhuǎn)換 Word。這樣設(shè)計(jì)的好處是每個(gè)函數(shù)只做一件事后續(xù)想改成 Web 接口或者把輸出從 Word 換成 PDF改動(dòng)都會(huì)很小。4.2 創(chuàng)建項(xiàng)目結(jié)構(gòu)我建議按下面的結(jié)構(gòu)組織文件grok-word-tool/ ├── venv/ # 虛擬環(huán)境 ├── main.py # 入口腳本 ├── grok_client.py # Grok API 調(diào)用封裝 └── output/ # 生成結(jié)果保存目錄grok_client.py負(fù)責(zé)和 API 打交道m(xù)ain.py負(fù)責(zé)流程編排。先把輸出目錄建好mkdir output4.3 編寫(xiě)核心代碼先寫(xiě)grok_client.py# 文件路徑grok_client.py import os from openai import OpenAI class GrokClient: def __init__(self): self.client OpenAI( api_keyos.environ.get(XAI_API_KEY), base_urlhttps://api.x.ai/v1, ) def generate_article(self, topic: str, max_words: int 800) - str: prompt ( f請(qǐng)圍繞「{topic}」寫(xiě)一篇結(jié)構(gòu)清晰的技術(shù)文章。\n f要求\n f1. 包含 2 到 4 個(gè)二級(jí)標(biāo)題\n f2. 每個(gè)段落內(nèi)容具體不要空泛\n f3. 正文控制在 {max_words} 字左右\n f4. 使用 Markdown 格式輸出。 ) response self.client.chat.completions.create( modelgrok-4.6, messages[ { role: system, content: 你是一個(gè)中文技術(shù)文章寫(xiě)作專(zhuān)家。, }, { role: user, content: prompt, }, ], temperature0.6, ) return response.choices[0].message.content這個(gè)類(lèi)里面做了兩件事初始化客戶(hù)端封裝文章生成方法。在生成提示詞時(shí)我把主題、字?jǐn)?shù)、格式要求都寫(xiě)進(jìn)去了這是為了讓 Grok 輸出更可控。接下來(lái)寫(xiě)main.py# 文件路徑main.py import os from grok_client import GrokClient def save_markdown(content: str, file_path: str) - None: with open(file_path, w, encodingutf-8) as f: f.write(content) print(fMarkdown 文件已保存{file_path}) def main(): topic input(請(qǐng)輸入文章主題).strip() if not topic: print(主題不能為空) return client GrokClient() content client.generate_article(topic) os.makedirs(output, exist_okTrue) md_path os.path.join(output, article.md) save_markdown(content, md_path) if __name__ __main__: main()運(yùn)行一下試試python main.py輸入一個(gè)主題例如“Python 裝飾器入門(mén)”過(guò)幾秒后打開(kāi)output/article.md應(yīng)該能看到一篇 Markdown 格式的文章。4.4 把 Grok 生成的文本加入 Word現(xiàn)在到了很多人問(wèn)的問(wèn)題怎么把 Grok 生成的文本轉(zhuǎn)成 Word。最簡(jiǎn)單的思路是直接讀取 Markdown 文本按行解析標(biāo)題和普通段落然后用 python-docx 寫(xiě)入 Word 文檔。這里要說(shuō)明一下python-docx 不原生支持 Markdown 渲染所以我們需要自己做簡(jiǎn)單解析。示例代碼只處理三種情況一級(jí)標(biāo)題、二級(jí)標(biāo)題、普通段落。對(duì)于其他 Markdown 語(yǔ)法比如列表、代碼塊你可以根據(jù)實(shí)際需求擴(kuò)展。在main.py中新增一個(gè)函數(shù)# 文件路徑main.py from docx import Document from docx.shared import Pt def markdown_to_word(md_path: str, docx_path: str) - None: doc Document() with open(md_path, r, encodingutf-8) as f: lines f.readlines() for line in lines: line line.strip() if not line: continue if line.startswith(## ): heading doc.add_heading(level1) run heading.add_run(line.replace(## , )) run.font.size Pt(18) elif line.startswith(### ): heading doc.add_heading(level2) run heading.add_run(line.replace(### , )) run.font.size Pt(15) else: doc.add_paragraph(line) doc.save(docx_path) print(fWord 文檔已保存{docx_path})然后在main()里調(diào)用def main(): topic input(請(qǐng)輸入文章主題).strip() if not topic: print(主題不能為空) return client GrokClient() content client.generate_article(topic) os.makedirs(output, exist_okTrue) md_path os.path.join(output, article.md) save_markdown(content, md_path) docx_path os.path.join(output, article.docx) markdown_to_word(md_path, docx_path)這個(gè)轉(zhuǎn)換函數(shù)的基本邏輯是遍歷 Markdown 的每一行判斷前綴。如果是##就在 Word 中插入一級(jí)標(biāo)題如果是###插入二級(jí)標(biāo)題否則插入普通段落。4.5 運(yùn)行與驗(yàn)證完整跑一遍python main.py正常情況下的輸出類(lèi)似請(qǐng)輸入文章主題Python 裝飾器入門(mén) Markdown 文件已保存output/article.md Word 文檔已保存output/article.docx打開(kāi)output/article.docx你會(huì)看到結(jié)構(gòu)和 Markdown 文件基本對(duì)應(yīng)標(biāo)題是標(biāo)題樣式段落是正文。到這里一條“Grok 生成文本 → 保存 Markdown → 導(dǎo)出 Word”的自動(dòng)化鏈路就打通了。如果你想把生成的文本加入 Word 的指定位置比如在文檔開(kāi)頭插入封面標(biāo)題或者把不同章節(jié)寫(xiě)到不同段落只需要在markdown_to_word中增加對(duì)應(yīng)邏輯即可。5. 常見(jiàn)問(wèn)題與排查思路實(shí)際使用中很少有人一次就能跑通。下面我把常見(jiàn)問(wèn)題整理成一張表格再逐個(gè)展開(kāi)說(shuō)。問(wèn)題現(xiàn)象常見(jiàn)原因解決思路401 認(rèn)證失敗API Key 無(wú)效或未正確設(shè)置檢查環(huán)境變量和 Key 是否復(fù)制完整404 模型不存在model 參數(shù)寫(xiě)錯(cuò)到官方文檔確認(rèn)當(dāng)前模型標(biāo)識(shí)429 請(qǐng)求過(guò)多觸發(fā)限流增加重試策略降低請(qǐng)求頻率請(qǐng)求超時(shí)網(wǎng)絡(luò)問(wèn)題或響應(yīng)時(shí)間過(guò)長(zhǎng)設(shè)置合理的超時(shí)時(shí)間和重試機(jī)制輸出內(nèi)容為 null內(nèi)容被安全策略攔截或參數(shù)錯(cuò)誤檢查提示詞換一種表達(dá)方式生成的 Word 格式不對(duì)Markdown 解析不完整增強(qiáng)解析邏輯處理列表和代碼塊5.1 認(rèn)證與權(quán)限問(wèn)題如果你遇到AuthenticationError首先檢查環(huán)境變量是否真的設(shè)置成功了。在終端里輸入echo $XAI_API_KEY如果輸出為空說(shuō)明環(huán)境變量沒(méi)設(shè)置或者終端會(huì)話(huà)沒(méi)有重新加載。如果輸出正常再確認(rèn) Key 是否復(fù)制完整很多 Key 末尾多一個(gè)空格都會(huì)導(dǎo)致認(rèn)證失敗。另外要注意不要把 Key 提交到 Git 倉(cāng)庫(kù)。建議在.gitignore中加入.env文件或者用密鑰管理服務(wù)保存敏感信息。5.2 請(qǐng)求超時(shí)與限流請(qǐng)求超時(shí)是調(diào)用大模型 API 時(shí)最常見(jiàn)的網(wǎng)絡(luò)類(lèi)問(wèn)題。原因主要有兩類(lèi)一是本地網(wǎng)絡(luò)到 API 服務(wù)之間的鏈路不穩(wěn)定二是生成內(nèi)容較長(zhǎng)導(dǎo)致響應(yīng)時(shí)間超過(guò)默認(rèn)超時(shí)設(shè)置。處理方式是在創(chuàng)建客戶(hù)端時(shí)增加超時(shí)參數(shù)client OpenAI( api_keyos.environ.get(XAI_API_KEY), base_urlhttps://api.x.ai/v1, timeout120.0, )遇到限流時(shí)不要死循環(huán)重試應(yīng)該用指數(shù)退避策略第一次等待 1 秒第二次等待 2 秒第三次等待 4 秒逐漸加大間隔。這樣既不會(huì)把自己本地請(qǐng)求堵死也能減少對(duì)服務(wù)端的壓力。5.3 輸出解析問(wèn)題有時(shí)候 API 調(diào)用成功了但拿到的message.content是None。這通常有兩種情況一是模型返回了內(nèi)容審核拒絕結(jié)果二是流式輸出模式下沒(méi)有正確讀取內(nèi)容。在非流式模式下建議在解析前先做一次判斷message response.choices[0].message content message.content or if not content: print(模型沒(méi)有返回內(nèi)容請(qǐng)檢查提示詞是否觸發(fā)了安全過(guò)濾)另外如果模型在輸出中使用了 Markdown 表格、代碼塊等復(fù)雜結(jié)構(gòu)你的 Word 轉(zhuǎn)換工具不一定能正確處理。這時(shí)可以在提示詞里明確要求“不要輸出表格不要輸出圍欄代碼塊”減少解析負(fù)擔(dān)。5.4 排查清單當(dāng)你遇到問(wèn)題但不知道從哪里下手時(shí)按下面的順序排查確認(rèn) API Key 有效并且環(huán)境變量能讀到。確認(rèn)模型名與官方文檔一致。用最簡(jiǎn)單的quick_start.py測(cè)試排除業(yè)務(wù)代碼干擾。查看完整報(bào)錯(cuò)堆棧區(qū)分是網(wǎng)絡(luò)錯(cuò)誤、認(rèn)證錯(cuò)誤還是參數(shù)錯(cuò)誤。在官方文檔或社區(qū)搜索報(bào)錯(cuò)信息。大多數(shù)問(wèn)題都出在模型名和環(huán)境變量上先把這兩個(gè)固定住能解決一半以上的故障。6. 最佳實(shí)踐與工程建議代碼能跑通只是第一步。如果要做成穩(wěn)定可用的工程還需要考慮提示詞設(shè)計(jì)、錯(cuò)誤處理、成本控制和安全合規(guī)等幾個(gè)方面。6.1 提示詞設(shè)計(jì)同樣一個(gè)模型提示詞寫(xiě)得好不好輸出質(zhì)量可能差很多。我一般會(huì)把提示詞拆成三部分角色設(shè)定告訴模型它是什么角色。任務(wù)描述告訴模型要完成什么任務(wù)。輸出約束告訴模型格式要求、字?jǐn)?shù)要求、內(nèi)容邊界。例如prompt ( 你是一名資深 Python 工程師。\n 請(qǐng)為下面的需求編寫(xiě)一段代碼并解釋關(guān)鍵點(diǎn)\n f需求{requirement}\n 要求代碼必須完整可運(yùn)行解釋部分不超過(guò) 200 字。 )在工程化場(chǎng)景中建議把提示詞模板抽成單獨(dú)的配置文件或模板文件方便業(yè)務(wù)人員直接修改不需要改代碼。6.2 錯(cuò)誤處理與重試任何依賴(lài)外部 API 的程序都必須假設(shè)網(wǎng)絡(luò)和上游服務(wù)不可靠。我在實(shí)際代碼中至少會(huì)做三層處理捕獲網(wǎng)絡(luò)異常并記錄日志。對(duì) 429、500、503 這類(lèi)錯(cuò)誤做指數(shù)退避重試。多次重試仍失敗時(shí)返回友好的錯(cuò)誤信息而不是直接把堆棧拋給用戶(hù)。下面是一個(gè)簡(jiǎn)單的重試示例import time from openai import OpenAI client OpenAI(api_keyyour-key, base_urlhttps://api.x.ai/v1) def call_with_retry(messages, max_retries3): for attempt in range(max_retries): try: response client.chat.completions.create( modelgrok-4.6, messagesmessages, ) return response.choices[0].message.content except Exception as e: if attempt max_retries - 1: raise wait 2 ** attempt print(f請(qǐng)求失敗{wait} 秒后重試{e}) time.sleep(wait)這個(gè)示例使用了max_retries參數(shù)限制重試次數(shù)等待時(shí)間按 1 秒、2 秒、4 秒遞增。6.3 上下文與成本控制大模型調(diào)用的費(fèi)用和輸入輸出 token 數(shù)量直接相關(guān)?？刂瞥杀镜暮诵氖侄问强刂粕舷挛拈L(zhǎng)度。在多輪對(duì)話(huà)場(chǎng)景中如果用戶(hù)一直發(fā)消息歷史記錄會(huì)越來(lái)越長(zhǎng)。常見(jiàn)做法是只保留最近幾輪消息或者用摘要代替舊消息。比如設(shè)置一個(gè)最大消息數(shù)超過(guò)后把最舊的消息壓縮成一句摘要。另外建議在生成任務(wù)中明確限制輸出長(zhǎng)度。如果你的文章只需要 800 字就在提示詞里寫(xiě)清楚避免模型輸出一大段冗余內(nèi)容。6.4 安全與合規(guī)使用 Grok API 時(shí)必須遵守官方服務(wù)條款只通過(guò)正規(guī)渠道獲取 API Key不要使用任何未經(jīng)授權(quán)的接入方式。不要嘗試讓模型生成違法、攻擊性、歧視性?xún)?nèi)容也不要使用所謂的“免審核提示詞”一類(lèi)技巧。作為開(kāi)發(fā)者尤其是后端開(kāi)發(fā)者需要對(duì)用戶(hù)通過(guò)你的工具提交的內(nèi)容做基本的安全過(guò)濾。如果這個(gè)工具面向公眾開(kāi)放建議在前后端都加入敏感內(nèi)容檢測(cè)機(jī)制避免你的應(yīng)用成為內(nèi)容風(fēng)險(xiǎn)傳播的入口。另外日志中不要記錄完整的用戶(hù)輸入和模型輸出尤其是涉及個(gè)人隱私或業(yè)務(wù)敏感數(shù)據(jù)的內(nèi)容。如果必須記錄也要做脫敏處理。6.5 可維護(hù)性當(dāng)你把“AI 能力”集成到業(yè)務(wù)系統(tǒng)后可維護(hù)性往往比炫酷的功能更重要。我建議做到以下幾點(diǎn)模型名不要散落在業(yè)務(wù)代碼里統(tǒng)一放在配置文件中。請(qǐng)求參數(shù)、提示詞模板、重試策略和業(yè)務(wù)邏輯分離。給每個(gè)調(diào)用增加唯一請(qǐng)求 ID方便在日志中追蹤問(wèn)題。在代碼注釋里寫(xiě)清楚每個(gè)參數(shù)的用途和取值范圍。這樣的代碼一開(kāi)始寫(xiě)起來(lái)略顯繁瑣但維護(hù)時(shí)會(huì)非常舒服。7. 總結(jié)與下一步學(xué)習(xí)建議這篇文章從 Grok 4.6 的概念出發(fā)完整走了一遍 API 接入、文本生成、Markdown 保存、Word 導(dǎo)出的全流程。核心收獲可以概括成三點(diǎn)第一Grok API 的接入方式不復(fù)雜熟悉 OpenAI 兼容格式后切換模型非常容易真正需要花時(shí)間的是提示詞設(shè)計(jì)和輸出解析。第二把 AI 生成內(nèi)容轉(zhuǎn)成 Word 這類(lèi)需求本質(zhì)上是一個(gè)文本處理問(wèn)題不要指望現(xiàn)成庫(kù)能一步到位先用簡(jiǎn)單解析滿(mǎn)足 80% 的需求后續(xù)再根據(jù)實(shí)際情況增強(qiáng)。第三工程化使用大模型 API重點(diǎn)在于錯(cuò)誤處理、成本控制和內(nèi)容安全。這三件事沒(méi)有做好功能再炫酷也撐不住真實(shí)業(yè)務(wù)。下一步你可以嘗試幾個(gè)方向把當(dāng)前腳本改造成 Flask 或 FastAPI 接口做成一個(gè)內(nèi)部網(wǎng)頁(yè)工具在 Markdown 轉(zhuǎn)換中支持更多語(yǔ)法比如列表、代碼塊、圖片或者給工具加上流式輸出讓用戶(hù)看到逐字生成的效果。有條件的話(huà)建議你拿著本文的示例代碼親自動(dòng)手跑一遍再改一改提示詞看看不同參數(shù)對(duì)生成結(jié)果的影響。只有自己調(diào)過(guò)一遍參數(shù)踩過(guò)幾個(gè)坑才真正算是把這套流程用熟了。如果本文對(duì)你有幫助可以先收藏備用后面用到的時(shí)候直接照著操作。