：大模型、RAG、智能體、MCP，收藏這篇就夠了！)
1. 大模型、RAG、智能體、MCP 到底各管什么一張知識(shí)地圖先建立起來(lái)剛接觸 AI 技術(shù)棧的開發(fā)者最容易卡在概念混戰(zhàn)里大模型、RAG、智能體、MCP 這四個(gè)詞天天見但真讓你說(shuō)清楚它們各自解決什么問(wèn)題、誰(shuí)依賴誰(shuí)很多人會(huì)含糊。我試過(guò)把官方文檔翻一遍再動(dòng)手發(fā)現(xiàn)光看定義沒(méi)用必須把它們放進(jìn)同一條數(shù)據(jù)流里看關(guān)系立刻就清楚了。先給一個(gè)最直白的類比。大模型是「大腦」負(fù)責(zé)理解和生成RAG 是「開卷考試時(shí)遞進(jìn)來(lái)的參考書」讓大腦回答前先查資料智能體是「會(huì)自己拆任務(wù)、調(diào)工具的執(zhí)行者」它決定什么時(shí)候翻書、什么時(shí)候算數(shù)、什么時(shí)候問(wèn)別人MCP 則是「統(tǒng)一的插座標(biāo)準(zhǔn)」讓智能體能即插即用地接上各種外部工具和數(shù)據(jù)源而不用每接一個(gè)工具就重寫一遍膠水代碼。這四個(gè)東西不是并列關(guān)系而是層層疊加的協(xié)作關(guān)系。大模型提供基礎(chǔ)推理能力RAG 解決大模型知識(shí)過(guò)時(shí)和幻覺的問(wèn)題智能體在 RAG 之上加入規(guī)劃與工具調(diào)用MCP 把工具接入這件事標(biāo)準(zhǔn)化。你完全可以只用大模型也可以只加 RAG但一旦要做能自主完成復(fù)雜任務(wù)的系統(tǒng)四者就會(huì)自然串起來(lái)。對(duì)剛?cè)腴T的開發(fā)者來(lái)說(shuō)最實(shí)用的認(rèn)知框架是先問(wèn)「這個(gè)任務(wù)需要模型知道它訓(xùn)練時(shí)不知道的東西嗎」需要就上 RAG再問(wèn)「這個(gè)任務(wù)需要多步?jīng)Q策和調(diào)用外部能力嗎」需要就上智能體最后問(wèn)「工具會(huì)越來(lái)越多、要跨模型跨平臺(tái)復(fù)用嗎」需要就上 MCP。按這個(gè)順序判斷你不會(huì)一上來(lái)就堆一堆用不上的組件。下面這張對(duì)照表是我自己整理后一直在用的建議先收藏后面每一節(jié)都會(huì)圍繞它展開。概念解決的核心問(wèn)題關(guān)鍵輸入關(guān)鍵輸出典型依賴大模型理解與生成自然語(yǔ)言、代碼Prompt、上下文文本/結(jié)構(gòu)化結(jié)果算力、推理服務(wù)RAG知識(shí)時(shí)效性與事實(shí)準(zhǔn)確性用戶問(wèn)題、向量庫(kù)帶依據(jù)的回答大模型、向量庫(kù)、嵌入模型智能體多步任務(wù)規(guī)劃與執(zhí)行目標(biāo)、工具列表完成的任務(wù)結(jié)果大模型、工具、記憶MCP工具接入的標(biāo)準(zhǔn)化工具定義、資源可被模型發(fā)現(xiàn)的工具智能體、MCP 服務(wù)端理解這張表之后你會(huì)發(fā)現(xiàn)很多「AI 應(yīng)用」其實(shí)就是這四個(gè)模塊的不同組合。客服機(jī)器人通常是「大模型 RAG」自動(dòng)化辦公助手是「大模型 智能體 MCP」而一個(gè)能查數(shù)據(jù)庫(kù)、能發(fā)郵件、能調(diào) API 的復(fù)雜系統(tǒng)四個(gè)全用上。這一節(jié)的目標(biāo)不是讓你立刻寫代碼而是先在心里建好地圖。地圖建好了后面配置和驗(yàn)證才不會(huì)迷路。接下來(lái)我會(huì)先講怎么準(zhǔn)備一個(gè)統(tǒng)一的模型接入入口因?yàn)闊o(wú)論你練 RAG 還是智能體都得先有一個(gè)能穩(wěn)定調(diào)用大模型的通道否則后面每一步都會(huì)被環(huán)境問(wèn)題打斷。2. 用 TaoToken 打通大模型調(diào)用入口RAG 與智能體的統(tǒng)一前置不管你后面要練 RAG 還是智能體第一步都是讓代碼能穩(wěn)定調(diào)到大模型。很多新手卡在這一步不同廠商的接口格式不一樣換一個(gè)模型就要改一遍代碼練 RAG 時(shí)用 A 模型練智能體時(shí)想換 B 模型結(jié)果配置全亂。我的做法是先接一個(gè)兼容 OpenAI 接口規(guī)范的統(tǒng)一入口把模型調(diào)用這件事固定下來(lái)后面所有實(shí)驗(yàn)都復(fù)用同一套配置。TaoToken 就是這樣一個(gè)入口官網(wǎng)是 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content API 地址是 https://taotoken.net/api 。它的接口遵循 OpenAI 兼容格式意味著你之前寫過(guò)的 openai 庫(kù)調(diào)用代碼基本不用改只換 base_url 和 key 就能跑。這對(duì)練 RAG 和智能體特別友好因?yàn)檫@兩個(gè)方向都會(huì)頻繁切換模型做對(duì)比。先說(shuō)清楚它適合誰(shuí)如果你是想系統(tǒng)學(xué)習(xí) AI 技術(shù)棧的開發(fā)者需要一個(gè)穩(wěn)定的模型調(diào)用通道來(lái)跑通 RAG、智能體、MCP 的完整鏈路那它正好合適。如果你只是偶爾問(wèn)幾個(gè)問(wèn)題直接用網(wǎng)頁(yè)版模型對(duì)話就夠了不必折騰 API。但只要你打算寫代碼、做實(shí)驗(yàn)、搭 demo統(tǒng)一入口就是剛需。準(zhǔn)備工作分三步。第一步注冊(cè)并登錄后進(jìn)入控制臺(tái)地址是 https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_contentconsoleutm_campaignrewrite 在里面找到 API Keys 管理頁(yè)面地址是 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi-keysutm_campaignrewrite 創(chuàng)建一個(gè)新的 Key 并復(fù)制保存。注意 Key 只在創(chuàng)建時(shí)完整顯示一次丟了就得重建。第二步確認(rèn)你要用的模型 ID。不同任務(wù)適合不同模型練 RAG 時(shí)通常選上下文窗口大、指令遵循好的模型練智能體時(shí)更看重工具調(diào)用能力。你可以在模型對(duì)話頁(yè)面 https://taotoken.net/chat?utm_sourcetaotoken_aicg_blog_endutm_contentmodel_chatutm_campaignrewrite 里先手動(dòng)試幾個(gè)模型感受一下差異再?zèng)Q定代碼里默認(rèn)用哪個(gè)。第三步把配置寫進(jìn)環(huán)境變量不要硬編碼在代碼里。這是很多人踩過(guò)的坑Key 寫死在腳本里一提交到倉(cāng)庫(kù)就泄露。正確做法是用 .env 文件或系統(tǒng)環(huán)境變量管理。下面是一個(gè) .env 示例路徑放在項(xiàng)目根目錄即可。# .env 文件放在項(xiàng)目根目錄 TAOTOKEN_API_KEYsk-你的實(shí)際Key TAOTOKEN_BASE_URLhttps://taotoken.net/api TAOTOKEN_MODELgpt-4o-mini如果你用的是 Python可以這樣讀取并初始化客戶端。注意 base_url 一定要帶上 /api 后綴這是最常見的配置錯(cuò)誤之一。import os from openai import OpenAI from dotenv import load_dotenv load_dotenv() client OpenAI( api_keyos.getenv(TAOTOKEN_API_KEY), base_urlos.getenv(TAOTOKEN_BASE_URL), ) resp client.chat.completions.create( modelos.getenv(TAOTOKEN_MODEL), messages[{role: user, content: 用一句話解釋什么是 RAG}], ) print(resp.choices[0].message.content)如果你更習(xí)慣用 Node.js配置邏輯完全一樣只是庫(kù)不同。下面是對(duì)應(yīng)片段。// 需要先 npm install openai dotenv import OpenAI from openai; import dotenv/config; const client new OpenAI({ apiKey: process.env.TAOTOKEN_API_KEY, baseURL: process.env.TAOTOKEN_BASE_URL, }); const resp await client.chat.completions.create({ model: process.env.TAOTOKEN_MODEL, messages: [{ role: user, content: 用一句話解釋什么是 MCP }], }); console.log(resp.choices[0].message.content);這里要強(qiáng)調(diào)一個(gè)關(guān)鍵點(diǎn)無(wú)論你后面用 LangChain、LlamaIndex 還是自己手寫 RAG底層模型調(diào)用都可以指向同一個(gè) base_url。這樣你在對(duì)比不同模型對(duì) RAG 效果的影響時(shí)只需要改一個(gè)環(huán)境變量不用動(dòng)業(yè)務(wù)代碼。智能體框架也是同理工具調(diào)用最終還是要落到模型接口上。還有一個(gè)容易被忽略的準(zhǔn)備確認(rèn)你的網(wǎng)絡(luò)環(huán)境能正常訪問(wèn)該 API 地址。如果你在公司內(nèi)網(wǎng)或受限環(huán)境先確認(rèn)出網(wǎng)策略避免后面調(diào)試時(shí)把網(wǎng)絡(luò)問(wèn)題誤判成代碼問(wèn)題。配置完成后先別急著搭 RAG下一節(jié)我會(huì)給你一份可直接復(fù)制的完整配置把大模型、RAG、智能體、MCP 四塊的最小示例串起來(lái)讓你一次跑通整條鏈路。3. 可復(fù)制的最小配置把大模型、RAG、智能體、MCP 串成一條鏈路這一節(jié)是整篇的核心我會(huì)給你一份可以直接復(fù)制運(yùn)行的最小配置把四個(gè)概念串起來(lái)。不要被「四個(gè)」嚇到最小示例里每個(gè)模塊只保留最必要的部分目的是讓你看到它們?nèi)绾螀f(xié)作而不是做一個(gè)生產(chǎn)級(jí)系統(tǒng)。跑通之后你再按需替換成真實(shí)組件。先看整體結(jié)構(gòu)。我們做一個(gè)「能查本地知識(shí)庫(kù)并調(diào)用工具」的小助手用戶提問(wèn)后智能體先判斷是否需要查資料需要就通過(guò) RAG 檢索本地文檔檢索結(jié)果連同問(wèn)題一起交給大模型生成回答如果問(wèn)題需要計(jì)算或查外部數(shù)據(jù)智能體通過(guò) MCP 調(diào)用對(duì)應(yīng)工具。整個(gè)流程用一份配置文件描述代碼只負(fù)責(zé)執(zhí)行。先建項(xiàng)目結(jié)構(gòu)保持簡(jiǎn)單ai-stack-demo/ ├── .env ├── config.toml ├── main.py ├── rag_store/ │ └── docs.json └── mcp_servers/ └── calc_server.py配置文件用 TOML把模型、RAG、智能體、MCP 四塊參數(shù)集中管理。這樣你調(diào)參時(shí)只改一個(gè)文件不用滿項(xiàng)目找。# config.toml [model] base_url https://taotoken.net/api model_id gpt-4o-mini temperature 0.3 max_tokens 1024 [rag] enabled true store_path rag_store/docs.json top_k 3 chunk_size 300 [agent] max_steps 5 enable_reflection true [mcp] enabled true servers [mcp_servers/calc_server.py]RAG 部分最小實(shí)現(xiàn)不需要向量數(shù)據(jù)庫(kù)先用一個(gè) JSON 文件存文檔片段用關(guān)鍵詞匹配做檢索目的是讓你看清「檢索 → 拼接上下文 → 生成」這條鏈路。真實(shí)項(xiàng)目里把這里的檢索函數(shù)換成向量庫(kù)查詢即可。# rag.py import json def load_docs(path): with open(path, r, encodingutf-8) as f: return json.load(f) def retrieve(query, docs, top_k3): # 最小實(shí)現(xiàn)按關(guān)鍵詞命中數(shù)排序真實(shí)項(xiàng)目替換為向量檢索 scored [] for d in docs: score sum(1 for kw in query if kw in d[text]) scored.append((score, d)) scored.sort(keylambda x: x[0], reverseTrue) return [d for _, d in scored[:top_k]] def build_context(query, docs): hits retrieve(query, docs) return \n.join(f[{i1}] {h[text]} for i, h in enumerate(hits))智能體部分最小實(shí)現(xiàn)是一個(gè)循環(huán)讓模型決定下一步是「直接回答」還是「調(diào)用工具」最多循環(huán) max_steps 次。這里用 JSON 格式約定模型的輸出方便解析。# agent.py import json def run_agent(client, model, question, context, tools, max_steps5): messages [ {role: system, content: 你可以調(diào)用工具。需要工具時(shí)輸出 JSON{\tool\:\名稱\,\args\:{...}}否則直接回答。}, {role: user, content: f參考資料\n{context}\n\n問(wèn)題{question}}, ] for _ in range(max_steps): resp client.chat.completions.create(modelmodel, messagesmessages) content resp.choices[0].message.content try: action json.loads(content) if tool in action: result tools[action[tool]](**action.get(args, {})) messages.append({role: assistant, content: content}) messages.append({role: user, content: f工具返回{result}}) continue except json.JSONDecodeError: pass return content return 達(dá)到最大步數(shù)未完成MCP 部分最小實(shí)現(xiàn)用一個(gè)本地 Python 函數(shù)模擬工具服務(wù)端真實(shí)項(xiàng)目里換成標(biāo)準(zhǔn) MCP server。這里關(guān)鍵是讓工具「可被發(fā)現(xiàn)」智能體通過(guò)配置知道有哪些工具可用。# mcp_servers/calc_server.py def add(a, b): return a b def multiply(a, b): return a * b TOOLS { add: add, multiply: multiply, }主程序把四塊拼起來(lái)讀取配置、加載文檔、注冊(cè)工具、跑智能體。# main.py import os, json, tomllib from openai import OpenAI from dotenv import load_dotenv from rag import load_docs, build_context from agent import run_agent from mcp_servers.calc_server import TOOLS load_dotenv() with open(config.toml, rb) as f: cfg tomllib.load(f) client OpenAI( api_keyos.getenv(TAOTOKEN_API_KEY), base_urlcfg[model][base_url], ) docs load_docs(cfg[rag][store_path]) question RAG 和智能體有什么區(qū)別順便幫我算 12 乘 8 context build_context(question, docs) if cfg[rag][enabled] else answer run_agent( client, cfg[model][model_id], question, context, TOOLS, cfg[agent][max_steps], ) print(answer)這份配置的價(jià)值在于四個(gè)概念不再是抽象名詞而是四個(gè)可以單獨(dú)開關(guān)的模塊。你可以把 rag.enabled 設(shè)為 false 看純大模型的表現(xiàn)也可以把 mcp.enabled 關(guān)掉看智能體退化后的行為。對(duì)照實(shí)驗(yàn)做幾次理解會(huì)深很多。下一節(jié)我們逐步驗(yàn)證每個(gè)模塊是否真的跑通。4. 逐步驗(yàn)證每個(gè)模塊從單模型調(diào)用到完整鏈路跑通配置寫好了不代表跑通了必須一步步驗(yàn)證。我的習(xí)慣是從最底層往上驗(yàn)每層單獨(dú)確認(rèn)出問(wèn)題時(shí)才能快速定位是哪一塊的鍋。這一節(jié)給你一份可執(zhí)行的操作清單按順序做每步都有預(yù)期結(jié)果。第一步驗(yàn)證大模型調(diào)用。先不碰 RAG 和智能體只跑最基礎(chǔ)的對(duì)話確認(rèn) Key、base_url、模型 ID 三件套正確。from openai import OpenAI import os from dotenv import load_dotenv load_dotenv() client OpenAI( api_keyos.getenv(TAOTOKEN_API_KEY), base_urlos.getenv(TAOTOKEN_BASE_URL), ) resp client.chat.completions.create( modelos.getenv(TAOTOKEN_MODEL), messages[{role: user, content: 回復(fù)連接成功}], ) print(resp.choices[0].message.content)預(yù)期結(jié)果是模型返回一句確認(rèn)文本。如果這一步就報(bào)錯(cuò)先別往下走直接跳到第 5 節(jié)排查。這一步通過(guò)說(shuō)明你的模型入口是通的后面所有問(wèn)題都不會(huì)是「連不上」導(dǎo)致的。第二步驗(yàn)證 RAG 檢索。單獨(dú)調(diào)用檢索函數(shù)確認(rèn)能從文檔里撈出相關(guān)內(nèi)容。準(zhǔn)備一個(gè) docs.json放幾條測(cè)試文檔。[ {id: 1, text: RAG 是檢索增強(qiáng)生成先檢索再生成}, {id: 2, text: 智能體可以規(guī)劃任務(wù)并調(diào)用工具}, {id: 3, text: MCP 是模型上下文協(xié)議標(biāo)準(zhǔn)化工具接入} ]然后單獨(dú)跑檢索from rag import load_docs, build_context docs load_docs(rag_store/docs.json) ctx build_context(RAG 是什么, docs) print(ctx)預(yù)期結(jié)果是打印出包含「RAG 是檢索增強(qiáng)生成」的上下文。如果檢索為空檢查關(guān)鍵詞是否匹配、文檔路徑是否正確。這一步通過(guò)說(shuō)明檢索鏈路沒(méi)問(wèn)題。第三步驗(yàn)證智能體循環(huán)。先不給工具只讓它回答確認(rèn)循環(huán)能正常退出。from agent import run_agent from openai import OpenAI import os from dotenv import load_dotenv load_dotenv() client OpenAI(api_keyos.getenv(TAOTOKEN_API_KEY), base_urlos.getenv(TAOTOKEN_BASE_URL)) ans run_agent(client, os.getenv(TAOTOKEN_MODEL), 你好, , {}, max_steps3) print(ans)預(yù)期結(jié)果是直接返回回答不進(jìn)入工具調(diào)用分支。如果它反復(fù)循環(huán)到最大步數(shù)說(shuō)明模型輸出格式不符合預(yù)期檢查 system prompt 里的 JSON 約定。第四步驗(yàn)證工具調(diào)用。給智能體一個(gè)明確需要計(jì)算的問(wèn)題看它是否觸發(fā)工具。from mcp_servers.calc_server import TOOLS ans run_agent(client, os.getenv(TAOTOKEN_MODEL), 幫我算 12 乘 8, , TOOLS, max_steps5) print(ans)預(yù)期結(jié)果是模型先輸出工具調(diào)用 JSON工具返回 96模型再基于結(jié)果給出最終回答。如果模型直接心算而不調(diào)工具說(shuō)明工具描述不夠清晰或者模型本身工具調(diào)用能力弱換一個(gè)更擅長(zhǎng) function calling 的模型再試。第五步跑完整鏈路。用 main.py 一次性驗(yàn)證四塊協(xié)作問(wèn)題里同時(shí)包含「需要查資料」和「需要計(jì)算」兩部分看它是否既用了 RAG 又用了工具。python main.py預(yù)期結(jié)果是回答里既引用了文檔內(nèi)容又給出了正確的計(jì)算結(jié)果。到這里四個(gè)模塊就算全部跑通了。整個(gè)過(guò)程我建議你每步都截圖或記錄輸出后面出問(wèn)題時(shí)對(duì)照著看能省很多時(shí)間。驗(yàn)證通過(guò)后你已經(jīng)有了一套可運(yùn)行的最小系統(tǒng)。接下來(lái)要做的不是加功能而是先搞清楚常見報(bào)錯(cuò)怎么排查因?yàn)檎鎸?shí)項(xiàng)目里 80% 的時(shí)間都花在排障上。5. 本篇常見報(bào)錯(cuò)排查401、local proxy failed、reading choices、OAuth跑通最小示例后你大概率會(huì)在某個(gè)環(huán)節(jié)遇到報(bào)錯(cuò)。這一節(jié)我把最常見的幾類錯(cuò)誤和排查路徑列出來(lái)都是真實(shí)會(huì)遇到的對(duì)照著查能快速定位。第一類401 未授權(quán)。這是最高頻的錯(cuò)誤幾乎都是 Key 的問(wèn)題。典型報(bào)錯(cuò)長(zhǎng)這樣openai.AuthenticationError: Error code: 401 - {error: {message: Invalid API key}}排查順序先確認(rèn) .env 里的 TAOTOKEN_API_KEY 是否完整復(fù)制有沒(méi)有多余空格或換行再確認(rèn)這個(gè) Key 是否被刪除或過(guò)期去 API Keys 頁(yè)面 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi-keysutm_campaignrewrite 重新生成一個(gè)最后確認(rèn)代碼讀取環(huán)境變量的時(shí)機(jī)load_dotenv() 必須在創(chuàng)建 client 之前調(diào)用。很多人把 load_dotenv() 寫在 client 之后導(dǎo)致讀到空值。第二類local proxy failed。這個(gè)報(bào)錯(cuò)通常出現(xiàn)在網(wǎng)絡(luò)層提示本地代理連接失敗。典型信息APIConnectionError: Connection error. local proxy failed遇到這個(gè)先檢查你的運(yùn)行環(huán)境是否有本地代理配置干擾比如系統(tǒng)環(huán)境變量里殘留的 HTTP_PROXY、HTTPS_PROXY。如果有臨時(shí)清掉再試。另外確認(rèn) base_url 拼寫正確必須是 https://taotoken.net/api 少寫 /api 或?qū)懗?http 都會(huì)連不上。如果你在容器里跑檢查容器網(wǎng)絡(luò)是否能出網(wǎng)。第三類reading choices 相關(guān)錯(cuò)誤。典型報(bào)錯(cuò)KeyError: choices或者TypeError: NoneType object is not subscriptable這通常意味著返回結(jié)構(gòu)和你預(yù)期的不一樣。原因可能是模型 ID 寫錯(cuò)了接口返回了錯(cuò)誤信息而不是正常結(jié)果但你的代碼直接去取 choices[0]。正確做法是先打印完整響應(yīng)再解析resp client.chat.completions.create(...) print(resp) # 先看結(jié)構(gòu) print(resp.choices[0].message.content)如果 resp 里沒(méi)有 choices看它的 error 字段通常是模型名不對(duì)或參數(shù)越界。確認(rèn)模型 ID 拼寫max_tokens 不要超過(guò)模型上限。第四類OAuth 相關(guān)報(bào)錯(cuò)。如果你在配置某些客戶端工具時(shí)看到 OAuth 失敗典型信息OAuth error: invalid_client這類問(wèn)題多出現(xiàn)在客戶端工具的授權(quán)配置環(huán)節(jié)。排查時(shí)確認(rèn)回調(diào)地址是否和配置一致客戶端 ID 和密鑰是否匹配。如果你用的是 Claude Code 這類工具配置時(shí)三件套必須齊全Base URL 填 https://taotoken.net/api Key 填你的 API KeyModel ID 填你要用的模型名。三者缺一不可少填一個(gè)就會(huì)出現(xiàn)授權(quán)或調(diào)用失敗。為了讓你對(duì)照更方便我把常見報(bào)錯(cuò)和排查方向整理成表報(bào)錯(cuò)關(guān)鍵詞最可能原因優(yōu)先排查401 Invalid API keyKey 錯(cuò)誤或未加載.env 內(nèi)容、load_dotenv 順序local proxy failed網(wǎng)絡(luò)或 base_url 錯(cuò)誤代理變量、/api 后綴reading choices響應(yīng)結(jié)構(gòu)異常模型 ID、打印完整響應(yīng)OAuth invalid_client授權(quán)配置不全Base URL、Key、Model ID 三件套排障的核心思路是「先分層再定位」先確認(rèn)是網(wǎng)絡(luò)層、認(rèn)證層還是解析層的問(wèn)題再針對(duì)性檢查。不要一看到報(bào)錯(cuò)就改代碼很多時(shí)候問(wèn)題在配置。如果你在接入過(guò)程中反復(fù)卡住可以直接去接入文檔 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite 對(duì)照官方說(shuō)明通常能快速找到對(duì)應(yīng)配置項(xiàng)。6. 從概念到落地按你的目標(biāo)選對(duì)下一步概念和最小示例都跑通之后下一步怎么走取決于你的目標(biāo)。我把常見路徑分成三類你對(duì)號(hào)入座即可。如果你的目標(biāo)是「驗(yàn)證模型效果、做對(duì)比實(shí)驗(yàn)」那重點(diǎn)應(yīng)該放在模型對(duì)話和參數(shù)調(diào)優(yōu)上。你可以用模型對(duì)話頁(yè)面 https://taotoken.net/chat?utm_sourcetaotoken_aicg_blog_endutm_contentmodel_chatutm_campaignrewrite 快速試不同模型對(duì)同一問(wèn)題的回答差異把表現(xiàn)好的模型 ID 記下來(lái)再寫進(jìn)你的 RAG 或智能體配置里。這個(gè)階段不用急著上復(fù)雜框架先把「哪個(gè)模型適合哪類任務(wù)」摸清楚。如果你的目標(biāo)是「長(zhǎng)期做編碼、搭 Agent 工作流」那重點(diǎn)應(yīng)該放在 Coding Plan 上地址是 https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding_planutm_campaignrewrite 。它適合需要持續(xù)調(diào)用模型、頻繁迭代代碼的場(chǎng)景。你可以把前面最小示例里的模型調(diào)用替換成 Coding Plan 的配置然后在真實(shí)項(xiàng)目里逐步把 RAG 的檢索換成向量庫(kù)、把 MCP 的本地工具換成標(biāo)準(zhǔn)服務(wù)端。每換一塊都回到第 4 節(jié)的驗(yàn)證清單重新跑一遍確保沒(méi)破壞原有鏈路。如果你的目標(biāo)是「先把接入和排障徹底搞明白」那就把 API Keys 和接入文檔這兩個(gè)頁(yè)面吃透。API Keys 頁(yè)面 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi-keysutm_campaignrewrite 管理你的憑證接入文檔 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite 有完整的參數(shù)說(shuō)明和示例。遇到報(bào)錯(cuò)先查文檔比在網(wǎng)上亂搜快得多。最后分享一個(gè)我自己的實(shí)用技巧把第 3 節(jié)的 config.toml 當(dāng)成你的「實(shí)驗(yàn)記錄本」。每次調(diào)整模型、檢索參數(shù)、工具列表都在配置里改而不是散落在代碼各處。這樣你回頭對(duì)比不同配置的效果時(shí)只需要保存不同的 toml 文件隨時(shí)切換。配合第 4 節(jié)的驗(yàn)證清單你就能用一套可復(fù)現(xiàn)的流程把大模型、RAG、智能體、MCP 這四個(gè)概念真正變成手上能跑的東西而不是停留在名詞解釋層面。 圖解AI核心技術(shù)：大模型、RAG、智能體、MCP，收藏這篇就夠了！
1. 大模型、RAG、智能體、MCP 到底各管什么一張知識(shí)地圖先建立起來(lái)剛接觸 AI 技術(shù)棧的開發(fā)者最容易卡在概念混戰(zhàn)里大模型、RAG、智能體、MCP 這四個(gè)詞天天見但真讓你說(shuō)清楚它們各自解決什么問(wèn)題、誰(shuí)依賴誰(shuí)很多人會(huì)含糊。我試過(guò)把官方文檔翻一遍再動(dòng)手發(fā)現(xiàn)光看定義沒(méi)用必須把它們放進(jìn)同一條數(shù)據(jù)流里看關(guān)系立刻就清楚了。先給一個(gè)最直白的類比。大模型是「大腦」負(fù)責(zé)理解和生成RAG 是「開卷考試時(shí)遞進(jìn)來(lái)的參考書」讓大腦回答前先查資料智能體是「會(huì)自己拆任務(wù)、調(diào)工具的執(zhí)行者」它決定什么時(shí)候翻書、什么時(shí)候算數(shù)、什么時(shí)候問(wèn)別人MCP 則是「統(tǒng)一的插座標(biāo)準(zhǔn)」讓智能體能即插即用地接上各種外部工具和數(shù)據(jù)源而不用每接一個(gè)工具就重寫一遍膠水代碼。這四個(gè)東西不是并列關(guān)系而是層層疊加的協(xié)作關(guān)系。大模型提供基礎(chǔ)推理能力RAG 解決大模型知識(shí)過(guò)時(shí)和幻覺的問(wèn)題智能體在 RAG 之上加入規(guī)劃與工具調(diào)用MCP 把工具接入這件事標(biāo)準(zhǔn)化。你完全可以只用大模型也可以只加 RAG但一旦要做能自主完成復(fù)雜任務(wù)的系統(tǒng)四者就會(huì)自然串起來(lái)。對(duì)剛?cè)腴T的開發(fā)者來(lái)說(shuō)最實(shí)用的認(rèn)知框架是先問(wèn)「這個(gè)任務(wù)需要模型知道它訓(xùn)練時(shí)不知道的東西嗎」需要就上 RAG再問(wèn)「這個(gè)任務(wù)需要多步?jīng)Q策和調(diào)用外部能力嗎」需要就上智能體最后問(wèn)「工具會(huì)越來(lái)越多、要跨模型跨平臺(tái)復(fù)用嗎」需要就上 MCP。按這個(gè)順序判斷你不會(huì)一上來(lái)就堆一堆用不上的組件。下面這張對(duì)照表是我自己整理后一直在用的建議先收藏后面每一節(jié)都會(huì)圍繞它展開。概念解決的核心問(wèn)題關(guān)鍵輸入關(guān)鍵輸出典型依賴大模型理解與生成自然語(yǔ)言、代碼Prompt、上下文文本/結(jié)構(gòu)化結(jié)果算力、推理服務(wù)RAG知識(shí)時(shí)效性與事實(shí)準(zhǔn)確性用戶問(wèn)題、向量庫(kù)帶依據(jù)的回答大模型、向量庫(kù)、嵌入模型智能體多步任務(wù)規(guī)劃與執(zhí)行目標(biāo)、工具列表完成的任務(wù)結(jié)果大模型、工具、記憶MCP工具接入的標(biāo)準(zhǔn)化工具定義、資源可被模型發(fā)現(xiàn)的工具智能體、MCP 服務(wù)端理解這張表之后你會(huì)發(fā)現(xiàn)很多「AI 應(yīng)用」其實(shí)就是這四個(gè)模塊的不同組合。客服機(jī)器人通常是「大模型 RAG」自動(dòng)化辦公助手是「大模型 智能體 MCP」而一個(gè)能查數(shù)據(jù)庫(kù)、能發(fā)郵件、能調(diào) API 的復(fù)雜系統(tǒng)四個(gè)全用上。這一節(jié)的目標(biāo)不是讓你立刻寫代碼而是先在心里建好地圖。地圖建好了后面配置和驗(yàn)證才不會(huì)迷路。接下來(lái)我會(huì)先講怎么準(zhǔn)備一個(gè)統(tǒng)一的模型接入入口因?yàn)闊o(wú)論你練 RAG 還是智能體都得先有一個(gè)能穩(wěn)定調(diào)用大模型的通道否則后面每一步都會(huì)被環(huán)境問(wèn)題打斷。2. 用 TaoToken 打通大模型調(diào)用入口RAG 與智能體的統(tǒng)一前置不管你后面要練 RAG 還是智能體第一步都是讓代碼能穩(wěn)定調(diào)到大模型。很多新手卡在這一步不同廠商的接口格式不一樣換一個(gè)模型就要改一遍代碼練 RAG 時(shí)用 A 模型練智能體時(shí)想換 B 模型結(jié)果配置全亂。我的做法是先接一個(gè)兼容 OpenAI 接口規(guī)范的統(tǒng)一入口把模型調(diào)用這件事固定下來(lái)后面所有實(shí)驗(yàn)都復(fù)用同一套配置。TaoToken 就是這樣一個(gè)入口官網(wǎng)是 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content API 地址是 https://taotoken.net/api 。它的接口遵循 OpenAI 兼容格式意味著你之前寫過(guò)的 openai 庫(kù)調(diào)用代碼基本不用改只換 base_url 和 key 就能跑。這對(duì)練 RAG 和智能體特別友好因?yàn)檫@兩個(gè)方向都會(huì)頻繁切換模型做對(duì)比。先說(shuō)清楚它適合誰(shuí)如果你是想系統(tǒng)學(xué)習(xí) AI 技術(shù)棧的開發(fā)者需要一個(gè)穩(wěn)定的模型調(diào)用通道來(lái)跑通 RAG、智能體、MCP 的完整鏈路那它正好合適。如果你只是偶爾問(wèn)幾個(gè)問(wèn)題直接用網(wǎng)頁(yè)版模型對(duì)話就夠了不必折騰 API。但只要你打算寫代碼、做實(shí)驗(yàn)、搭 demo統(tǒng)一入口就是剛需。準(zhǔn)備工作分三步。第一步注冊(cè)并登錄后進(jìn)入控制臺(tái)地址是 https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_contentconsoleutm_campaignrewrite 在里面找到 API Keys 管理頁(yè)面地址是 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi-keysutm_campaignrewrite 創(chuàng)建一個(gè)新的 Key 并復(fù)制保存。注意 Key 只在創(chuàng)建時(shí)完整顯示一次丟了就得重建。第二步確認(rèn)你要用的模型 ID。不同任務(wù)適合不同模型練 RAG 時(shí)通常選上下文窗口大、指令遵循好的模型練智能體時(shí)更看重工具調(diào)用能力。你可以在模型對(duì)話頁(yè)面 https://taotoken.net/chat?utm_sourcetaotoken_aicg_blog_endutm_contentmodel_chatutm_campaignrewrite 里先手動(dòng)試幾個(gè)模型感受一下差異再?zèng)Q定代碼里默認(rèn)用哪個(gè)。第三步把配置寫進(jìn)環(huán)境變量不要硬編碼在代碼里。這是很多人踩過(guò)的坑Key 寫死在腳本里一提交到倉(cāng)庫(kù)就泄露。正確做法是用 .env 文件或系統(tǒng)環(huán)境變量管理。下面是一個(gè) .env 示例路徑放在項(xiàng)目根目錄即可。# .env 文件放在項(xiàng)目根目錄 TAOTOKEN_API_KEYsk-你的實(shí)際Key TAOTOKEN_BASE_URLhttps://taotoken.net/api TAOTOKEN_MODELgpt-4o-mini如果你用的是 Python可以這樣讀取并初始化客戶端。注意 base_url 一定要帶上 /api 后綴這是最常見的配置錯(cuò)誤之一。import os from openai import OpenAI from dotenv import load_dotenv load_dotenv() client OpenAI( api_keyos.getenv(TAOTOKEN_API_KEY), base_urlos.getenv(TAOTOKEN_BASE_URL), ) resp client.chat.completions.create( modelos.getenv(TAOTOKEN_MODEL), messages[{role: user, content: 用一句話解釋什么是 RAG}], ) print(resp.choices[0].message.content)如果你更習(xí)慣用 Node.js配置邏輯完全一樣只是庫(kù)不同。下面是對(duì)應(yīng)片段。// 需要先 npm install openai dotenv import OpenAI from openai; import dotenv/config; const client new OpenAI({ apiKey: process.env.TAOTOKEN_API_KEY, baseURL: process.env.TAOTOKEN_BASE_URL, }); const resp await client.chat.completions.create({ model: process.env.TAOTOKEN_MODEL, messages: [{ role: user, content: 用一句話解釋什么是 MCP }], }); console.log(resp.choices[0].message.content);這里要強(qiáng)調(diào)一個(gè)關(guān)鍵點(diǎn)無(wú)論你后面用 LangChain、LlamaIndex 還是自己手寫 RAG底層模型調(diào)用都可以指向同一個(gè) base_url。這樣你在對(duì)比不同模型對(duì) RAG 效果的影響時(shí)只需要改一個(gè)環(huán)境變量不用動(dòng)業(yè)務(wù)代碼。智能體框架也是同理工具調(diào)用最終還是要落到模型接口上。還有一個(gè)容易被忽略的準(zhǔn)備確認(rèn)你的網(wǎng)絡(luò)環(huán)境能正常訪問(wèn)該 API 地址。如果你在公司內(nèi)網(wǎng)或受限環(huán)境先確認(rèn)出網(wǎng)策略避免后面調(diào)試時(shí)把網(wǎng)絡(luò)問(wèn)題誤判成代碼問(wèn)題。配置完成后先別急著搭 RAG下一節(jié)我會(huì)給你一份可直接復(fù)制的完整配置把大模型、RAG、智能體、MCP 四塊的最小示例串起來(lái)讓你一次跑通整條鏈路。3. 可復(fù)制的最小配置把大模型、RAG、智能體、MCP 串成一條鏈路這一節(jié)是整篇的核心我會(huì)給你一份可以直接復(fù)制運(yùn)行的最小配置把四個(gè)概念串起來(lái)。不要被「四個(gè)」嚇到最小示例里每個(gè)模塊只保留最必要的部分目的是讓你看到它們?nèi)绾螀f(xié)作而不是做一個(gè)生產(chǎn)級(jí)系統(tǒng)。跑通之后你再按需替換成真實(shí)組件。先看整體結(jié)構(gòu)。我們做一個(gè)「能查本地知識(shí)庫(kù)并調(diào)用工具」的小助手用戶提問(wèn)后智能體先判斷是否需要查資料需要就通過(guò) RAG 檢索本地文檔檢索結(jié)果連同問(wèn)題一起交給大模型生成回答如果問(wèn)題需要計(jì)算或查外部數(shù)據(jù)智能體通過(guò) MCP 調(diào)用對(duì)應(yīng)工具。整個(gè)流程用一份配置文件描述代碼只負(fù)責(zé)執(zhí)行。先建項(xiàng)目結(jié)構(gòu)保持簡(jiǎn)單ai-stack-demo/ ├── .env ├── config.toml ├── main.py ├── rag_store/ │ └── docs.json └── mcp_servers/ └── calc_server.py配置文件用 TOML把模型、RAG、智能體、MCP 四塊參數(shù)集中管理。這樣你調(diào)參時(shí)只改一個(gè)文件不用滿項(xiàng)目找。# config.toml [model] base_url https://taotoken.net/api model_id gpt-4o-mini temperature 0.3 max_tokens 1024 [rag] enabled true store_path rag_store/docs.json top_k 3 chunk_size 300 [agent] max_steps 5 enable_reflection true [mcp] enabled true servers [mcp_servers/calc_server.py]RAG 部分最小實(shí)現(xiàn)不需要向量數(shù)據(jù)庫(kù)先用一個(gè) JSON 文件存文檔片段用關(guān)鍵詞匹配做檢索目的是讓你看清「檢索 → 拼接上下文 → 生成」這條鏈路。真實(shí)項(xiàng)目里把這里的檢索函數(shù)換成向量庫(kù)查詢即可。# rag.py import json def load_docs(path): with open(path, r, encodingutf-8) as f: return json.load(f) def retrieve(query, docs, top_k3): # 最小實(shí)現(xiàn)按關(guān)鍵詞命中數(shù)排序真實(shí)項(xiàng)目替換為向量檢索 scored [] for d in docs: score sum(1 for kw in query if kw in d[text]) scored.append((score, d)) scored.sort(keylambda x: x[0], reverseTrue) return [d for _, d in scored[:top_k]] def build_context(query, docs): hits retrieve(query, docs) return \n.join(f[{i1}] {h[text]} for i, h in enumerate(hits))智能體部分最小實(shí)現(xiàn)是一個(gè)循環(huán)讓模型決定下一步是「直接回答」還是「調(diào)用工具」最多循環(huán) max_steps 次。這里用 JSON 格式約定模型的輸出方便解析。# agent.py import json def run_agent(client, model, question, context, tools, max_steps5): messages [ {role: system, content: 你可以調(diào)用工具。需要工具時(shí)輸出 JSON{\tool\:\名稱\,\args\:{...}}否則直接回答。}, {role: user, content: f參考資料\n{context}\n\n問(wèn)題{question}}, ] for _ in range(max_steps): resp client.chat.completions.create(modelmodel, messagesmessages) content resp.choices[0].message.content try: action json.loads(content) if tool in action: result tools[action[tool]](**action.get(args, {})) messages.append({role: assistant, content: content}) messages.append({role: user, content: f工具返回{result}}) continue except json.JSONDecodeError: pass return content return 達(dá)到最大步數(shù)未完成MCP 部分最小實(shí)現(xiàn)用一個(gè)本地 Python 函數(shù)模擬工具服務(wù)端真實(shí)項(xiàng)目里換成標(biāo)準(zhǔn) MCP server。這里關(guān)鍵是讓工具「可被發(fā)現(xiàn)」智能體通過(guò)配置知道有哪些工具可用。# mcp_servers/calc_server.py def add(a, b): return a b def multiply(a, b): return a * b TOOLS { add: add, multiply: multiply, }主程序把四塊拼起來(lái)讀取配置、加載文檔、注冊(cè)工具、跑智能體。# main.py import os, json, tomllib from openai import OpenAI from dotenv import load_dotenv from rag import load_docs, build_context from agent import run_agent from mcp_servers.calc_server import TOOLS load_dotenv() with open(config.toml, rb) as f: cfg tomllib.load(f) client OpenAI( api_keyos.getenv(TAOTOKEN_API_KEY), base_urlcfg[model][base_url], ) docs load_docs(cfg[rag][store_path]) question RAG 和智能體有什么區(qū)別順便幫我算 12 乘 8 context build_context(question, docs) if cfg[rag][enabled] else answer run_agent( client, cfg[model][model_id], question, context, TOOLS, cfg[agent][max_steps], ) print(answer)這份配置的價(jià)值在于四個(gè)概念不再是抽象名詞而是四個(gè)可以單獨(dú)開關(guān)的模塊。你可以把 rag.enabled 設(shè)為 false 看純大模型的表現(xiàn)也可以把 mcp.enabled 關(guān)掉看智能體退化后的行為。對(duì)照實(shí)驗(yàn)做幾次理解會(huì)深很多。下一節(jié)我們逐步驗(yàn)證每個(gè)模塊是否真的跑通。4. 逐步驗(yàn)證每個(gè)模塊從單模型調(diào)用到完整鏈路跑通配置寫好了不代表跑通了必須一步步驗(yàn)證。我的習(xí)慣是從最底層往上驗(yàn)每層單獨(dú)確認(rèn)出問(wèn)題時(shí)才能快速定位是哪一塊的鍋。這一節(jié)給你一份可執(zhí)行的操作清單按順序做每步都有預(yù)期結(jié)果。第一步驗(yàn)證大模型調(diào)用。先不碰 RAG 和智能體只跑最基礎(chǔ)的對(duì)話確認(rèn) Key、base_url、模型 ID 三件套正確。from openai import OpenAI import os from dotenv import load_dotenv load_dotenv() client OpenAI( api_keyos.getenv(TAOTOKEN_API_KEY), base_urlos.getenv(TAOTOKEN_BASE_URL), ) resp client.chat.completions.create( modelos.getenv(TAOTOKEN_MODEL), messages[{role: user, content: 回復(fù)連接成功}], ) print(resp.choices[0].message.content)預(yù)期結(jié)果是模型返回一句確認(rèn)文本。如果這一步就報(bào)錯(cuò)先別往下走直接跳到第 5 節(jié)排查。這一步通過(guò)說(shuō)明你的模型入口是通的后面所有問(wèn)題都不會(huì)是「連不上」導(dǎo)致的。第二步驗(yàn)證 RAG 檢索。單獨(dú)調(diào)用檢索函數(shù)確認(rèn)能從文檔里撈出相關(guān)內(nèi)容。準(zhǔn)備一個(gè) docs.json放幾條測(cè)試文檔。[ {id: 1, text: RAG 是檢索增強(qiáng)生成先檢索再生成}, {id: 2, text: 智能體可以規(guī)劃任務(wù)并調(diào)用工具}, {id: 3, text: MCP 是模型上下文協(xié)議標(biāo)準(zhǔn)化工具接入} ]然后單獨(dú)跑檢索from rag import load_docs, build_context docs load_docs(rag_store/docs.json) ctx build_context(RAG 是什么, docs) print(ctx)預(yù)期結(jié)果是打印出包含「RAG 是檢索增強(qiáng)生成」的上下文。如果檢索為空檢查關(guān)鍵詞是否匹配、文檔路徑是否正確。這一步通過(guò)說(shuō)明檢索鏈路沒(méi)問(wèn)題。第三步驗(yàn)證智能體循環(huán)。先不給工具只讓它回答確認(rèn)循環(huán)能正常退出。from agent import run_agent from openai import OpenAI import os from dotenv import load_dotenv load_dotenv() client OpenAI(api_keyos.getenv(TAOTOKEN_API_KEY), base_urlos.getenv(TAOTOKEN_BASE_URL)) ans run_agent(client, os.getenv(TAOTOKEN_MODEL), 你好, , {}, max_steps3) print(ans)預(yù)期結(jié)果是直接返回回答不進(jìn)入工具調(diào)用分支。如果它反復(fù)循環(huán)到最大步數(shù)說(shuō)明模型輸出格式不符合預(yù)期檢查 system prompt 里的 JSON 約定。第四步驗(yàn)證工具調(diào)用。給智能體一個(gè)明確需要計(jì)算的問(wèn)題看它是否觸發(fā)工具。from mcp_servers.calc_server import TOOLS ans run_agent(client, os.getenv(TAOTOKEN_MODEL), 幫我算 12 乘 8, , TOOLS, max_steps5) print(ans)預(yù)期結(jié)果是模型先輸出工具調(diào)用 JSON工具返回 96模型再基于結(jié)果給出最終回答。如果模型直接心算而不調(diào)工具說(shuō)明工具描述不夠清晰或者模型本身工具調(diào)用能力弱換一個(gè)更擅長(zhǎng) function calling 的模型再試。第五步跑完整鏈路。用 main.py 一次性驗(yàn)證四塊協(xié)作問(wèn)題里同時(shí)包含「需要查資料」和「需要計(jì)算」兩部分看它是否既用了 RAG 又用了工具。python main.py預(yù)期結(jié)果是回答里既引用了文檔內(nèi)容又給出了正確的計(jì)算結(jié)果。到這里四個(gè)模塊就算全部跑通了。整個(gè)過(guò)程我建議你每步都截圖或記錄輸出后面出問(wèn)題時(shí)對(duì)照著看能省很多時(shí)間。驗(yàn)證通過(guò)后你已經(jīng)有了一套可運(yùn)行的最小系統(tǒng)。接下來(lái)要做的不是加功能而是先搞清楚常見報(bào)錯(cuò)怎么排查因?yàn)檎鎸?shí)項(xiàng)目里 80% 的時(shí)間都花在排障上。5. 本篇常見報(bào)錯(cuò)排查401、local proxy failed、reading choices、OAuth跑通最小示例后你大概率會(huì)在某個(gè)環(huán)節(jié)遇到報(bào)錯(cuò)。這一節(jié)我把最常見的幾類錯(cuò)誤和排查路徑列出來(lái)都是真實(shí)會(huì)遇到的對(duì)照著查能快速定位。第一類401 未授權(quán)。這是最高頻的錯(cuò)誤幾乎都是 Key 的問(wèn)題。典型報(bào)錯(cuò)長(zhǎng)這樣openai.AuthenticationError: Error code: 401 - {error: {message: Invalid API key}}排查順序先確認(rèn) .env 里的 TAOTOKEN_API_KEY 是否完整復(fù)制有沒(méi)有多余空格或換行再確認(rèn)這個(gè) Key 是否被刪除或過(guò)期去 API Keys 頁(yè)面 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi-keysutm_campaignrewrite 重新生成一個(gè)最后確認(rèn)代碼讀取環(huán)境變量的時(shí)機(jī)load_dotenv() 必須在創(chuàng)建 client 之前調(diào)用。很多人把 load_dotenv() 寫在 client 之后導(dǎo)致讀到空值。第二類local proxy failed。這個(gè)報(bào)錯(cuò)通常出現(xiàn)在網(wǎng)絡(luò)層提示本地代理連接失敗。典型信息APIConnectionError: Connection error. local proxy failed遇到這個(gè)先檢查你的運(yùn)行環(huán)境是否有本地代理配置干擾比如系統(tǒng)環(huán)境變量里殘留的 HTTP_PROXY、HTTPS_PROXY。如果有臨時(shí)清掉再試。另外確認(rèn) base_url 拼寫正確必須是 https://taotoken.net/api 少寫 /api 或?qū)懗?http 都會(huì)連不上。如果你在容器里跑檢查容器網(wǎng)絡(luò)是否能出網(wǎng)。第三類reading choices 相關(guān)錯(cuò)誤。典型報(bào)錯(cuò)KeyError: choices或者TypeError: NoneType object is not subscriptable這通常意味著返回結(jié)構(gòu)和你預(yù)期的不一樣。原因可能是模型 ID 寫錯(cuò)了接口返回了錯(cuò)誤信息而不是正常結(jié)果但你的代碼直接去取 choices[0]。正確做法是先打印完整響應(yīng)再解析resp client.chat.completions.create(...) print(resp) # 先看結(jié)構(gòu) print(resp.choices[0].message.content)如果 resp 里沒(méi)有 choices看它的 error 字段通常是模型名不對(duì)或參數(shù)越界。確認(rèn)模型 ID 拼寫max_tokens 不要超過(guò)模型上限。第四類OAuth 相關(guān)報(bào)錯(cuò)。如果你在配置某些客戶端工具時(shí)看到 OAuth 失敗典型信息OAuth error: invalid_client這類問(wèn)題多出現(xiàn)在客戶端工具的授權(quán)配置環(huán)節(jié)。排查時(shí)確認(rèn)回調(diào)地址是否和配置一致客戶端 ID 和密鑰是否匹配。如果你用的是 Claude Code 這類工具配置時(shí)三件套必須齊全Base URL 填 https://taotoken.net/api Key 填你的 API KeyModel ID 填你要用的模型名。三者缺一不可少填一個(gè)就會(huì)出現(xiàn)授權(quán)或調(diào)用失敗。為了讓你對(duì)照更方便我把常見報(bào)錯(cuò)和排查方向整理成表報(bào)錯(cuò)關(guān)鍵詞最可能原因優(yōu)先排查401 Invalid API keyKey 錯(cuò)誤或未加載.env 內(nèi)容、load_dotenv 順序local proxy failed網(wǎng)絡(luò)或 base_url 錯(cuò)誤代理變量、/api 后綴reading choices響應(yīng)結(jié)構(gòu)異常模型 ID、打印完整響應(yīng)OAuth invalid_client授權(quán)配置不全Base URL、Key、Model ID 三件套排障的核心思路是「先分層再定位」先確認(rèn)是網(wǎng)絡(luò)層、認(rèn)證層還是解析層的問(wèn)題再針對(duì)性檢查。不要一看到報(bào)錯(cuò)就改代碼很多時(shí)候問(wèn)題在配置。如果你在接入過(guò)程中反復(fù)卡住可以直接去接入文檔 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite 對(duì)照官方說(shuō)明通常能快速找到對(duì)應(yīng)配置項(xiàng)。6. 從概念到落地按你的目標(biāo)選對(duì)下一步概念和最小示例都跑通之后下一步怎么走取決于你的目標(biāo)。我把常見路徑分成三類你對(duì)號(hào)入座即可。如果你的目標(biāo)是「驗(yàn)證模型效果、做對(duì)比實(shí)驗(yàn)」那重點(diǎn)應(yīng)該放在模型對(duì)話和參數(shù)調(diào)優(yōu)上。你可以用模型對(duì)話頁(yè)面 https://taotoken.net/chat?utm_sourcetaotoken_aicg_blog_endutm_contentmodel_chatutm_campaignrewrite 快速試不同模型對(duì)同一問(wèn)題的回答差異把表現(xiàn)好的模型 ID 記下來(lái)再寫進(jìn)你的 RAG 或智能體配置里。這個(gè)階段不用急著上復(fù)雜框架先把「哪個(gè)模型適合哪類任務(wù)」摸清楚。如果你的目標(biāo)是「長(zhǎng)期做編碼、搭 Agent 工作流」那重點(diǎn)應(yīng)該放在 Coding Plan 上地址是 https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding_planutm_campaignrewrite 。它適合需要持續(xù)調(diào)用模型、頻繁迭代代碼的場(chǎng)景。你可以把前面最小示例里的模型調(diào)用替換成 Coding Plan 的配置然后在真實(shí)項(xiàng)目里逐步把 RAG 的檢索換成向量庫(kù)、把 MCP 的本地工具換成標(biāo)準(zhǔn)服務(wù)端。每換一塊都回到第 4 節(jié)的驗(yàn)證清單重新跑一遍確保沒(méi)破壞原有鏈路。如果你的目標(biāo)是「先把接入和排障徹底搞明白」那就把 API Keys 和接入文檔這兩個(gè)頁(yè)面吃透。API Keys 頁(yè)面 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi-keysutm_campaignrewrite 管理你的憑證接入文檔 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite 有完整的參數(shù)說(shuō)明和示例。遇到報(bào)錯(cuò)先查文檔比在網(wǎng)上亂搜快得多。最后分享一個(gè)我自己的實(shí)用技巧把第 3 節(jié)的 config.toml 當(dāng)成你的「實(shí)驗(yàn)記錄本」。每次調(diào)整模型、檢索參數(shù)、工具列表都在配置里改而不是散落在代碼各處。這樣你回頭對(duì)比不同配置的效果時(shí)只需要保存不同的 toml 文件隨時(shí)切換。配合第 4 節(jié)的驗(yàn)證清單你就能用一套可復(fù)現(xiàn)的流程把大模型、RAG、智能體、MCP 這四個(gè)概念真正變成手上能跑的東西而不是停留在名詞解釋層面。