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