今年很多開發(fā)者的卡點(diǎn)已經(jīng)不是“大模型能做什么”而是“我明明調(diào)通了 API卻依然不知道怎么把它變成真正的應(yīng)用”?？戳艘淮蠖芽蚣芪臋n收藏了十幾個(gè)教程最后面對(duì)一個(gè)最簡(jiǎn)單的知識(shí)庫(kù)問(wèn)答需求還是不知道從哪里下手。這個(gè)問(wèn)題的根源不是缺少學(xué)習(xí)資料而是缺少一條“能親手跑完”的路徑。datawhalechina/happy-llm 這個(gè)開源項(xiàng)目恰好就是為這條路徑設(shè)計(jì)的。它把大模型應(yīng)用開發(fā)拆成一個(gè)個(gè)很小的節(jié)點(diǎn)每個(gè)節(jié)點(diǎn)都用最小可運(yùn)行代碼去驗(yàn)證一個(gè)知識(shí)點(diǎn)從“一句話調(diào)用大模型”開始一直走到 RAG、Agent、Web 應(yīng)用部署。這篇文章不打算簡(jiǎn)單復(fù)述項(xiàng)目介紹而是想結(jié)合 LLM 應(yīng)用開發(fā)的實(shí)際痛點(diǎn)把 happy-llm 背后的設(shè)計(jì)思路、技術(shù)鏈路、環(huán)境準(zhǔn)備、代碼實(shí)現(xiàn)和常見坑位完整梳理一遍。如果你正在學(xué) LLM 應(yīng)用開發(fā)或者準(zhǔn)備用大模型 API 搭一個(gè)真實(shí)項(xiàng)目這篇文章應(yīng)該能幫你少走很多彎路。1. 為什么 LLM 應(yīng)用開發(fā)總卡在“入門到放棄”先聊一個(gè)現(xiàn)象。很多開發(fā)者掌握 Python也了解神經(jīng)網(wǎng)絡(luò)的基本概念但一進(jìn)入大模型應(yīng)用開發(fā)領(lǐng)域就陷入三種典型困境。第一種困境是“只逛概念不動(dòng)手”。Token、temperature、system prompt、上下文窗口、微調(diào)、RAG、Agent每個(gè)詞都聽過(guò)每個(gè)詞都能聊兩句但真要寫代碼時(shí)腦子里只有一個(gè)client.chat.completions.create后面怎么做完全沒(méi)概念。第二種困境是“一上來(lái)就上框架”?？吹?LangChain、LlamaIndex 很火直接去讀框架文檔結(jié)果被 Chain、Agent、Tool、Memory 這些抽象概念繞暈?？蚣鼙旧頉](méi)有錯(cuò)但框架是給已經(jīng)理解底層邏輯的人用的加速器。如果你還沒(méi)親手調(diào)通過(guò)一次原生 API沒(méi)有自己拼過(guò) messages 數(shù)組沒(méi)有手動(dòng)處理過(guò)一次工具調(diào)用返回框架只會(huì)變成另一層黑盒。第三種困境是“代碼能跑但只會(huì)跑”。網(wǎng)上可以找到大量現(xiàn)成的 DEMO復(fù)制下來(lái)確實(shí)能運(yùn)行但換一個(gè)需求就不知道怎么改。這說(shuō)明沒(méi)有理解 API 請(qǐng)求和響應(yīng)結(jié)構(gòu)背后的工程邏輯上下文是狀態(tài)、輸出格式是契約、工具調(diào)用是循環(huán)、檢索質(zhì)量決定回答質(zhì)量。LLM 應(yīng)用和傳統(tǒng)軟件開發(fā)的本質(zhì)區(qū)別在于傳統(tǒng)接口的輸入輸出是確定的結(jié)構(gòu)而大模型 API 的輸出是概率性的文本。這意味著你必須額外做結(jié)構(gòu)化約束、上下文管理、結(jié)果校驗(yàn)和異常兜底。這一整套方法不是背概念能學(xué)會(huì)的必須通過(guò)一個(gè)接一個(gè)的最小可運(yùn)行代碼去練習(xí)。happy-llm 的意義就是幫你把這條路走通。2. HAPPY-LLM 是什么項(xiàng)目定位與設(shè)計(jì)理念happy-llm 是 Datawhale 社區(qū)維護(hù)的一個(gè)開源學(xué)習(xí)項(xiàng)目。Datawhale 在國(guó)內(nèi)開源社區(qū)里比較特殊它不只是發(fā)代碼還會(huì)組織大家一起學(xué)強(qiáng)調(diào)“開源學(xué)習(xí)”這件事本身。這個(gè)項(xiàng)目的名字里就帶著學(xué)習(xí)理念保持一個(gè)自己能堅(jiān)持的節(jié)奏用小的正向反饋把學(xué)習(xí)持續(xù)下去而不是一次性吞下全部知識(shí)。從項(xiàng)目設(shè)計(jì)來(lái)看它沒(méi)有追求大而全的理論覆蓋而是把目標(biāo)設(shè)定得非常明確讓一個(gè)有一定 Python 基礎(chǔ)的開發(fā)者通過(guò)一段不長(zhǎng)的學(xué)習(xí)時(shí)間親手跑完一條完整的 LLM 應(yīng)用開發(fā)主鏈路。從調(diào) API 開始到提示詞設(shè)計(jì)、結(jié)構(gòu)化輸出、流式輸出、多輪對(duì)話、RAG 檢索增強(qiáng)生成、Agent 工具調(diào)用最后落在一個(gè)可交互的 Web Demo 上。這里要做一個(gè)重要區(qū)分happy-llm 不是生產(chǎn)級(jí)框架不是 LangChain 的替代品也不是一個(gè)大模型推理引擎。你學(xué)完它不會(huì)得到一個(gè)可以直接上生產(chǎn)的高并發(fā)服務(wù)但你會(huì)得到比讀十篇科普文章更扎實(shí)的東西——對(duì) LLM 應(yīng)用開發(fā)主鏈路每個(gè)環(huán)節(jié)的真實(shí)體感。用一個(gè)表格來(lái)對(duì)比它和傳統(tǒng)學(xué)習(xí)方式、框架文檔的區(qū)別對(duì)比維度傳統(tǒng)理論教程直接啃框架文檔happy-llm 這類實(shí)戰(zhàn)學(xué)習(xí)項(xiàng)目學(xué)習(xí)起點(diǎn)從注意力機(jī)制講起從框架抽象概念講起從一行能跑的 API 調(diào)用講起代碼量少以原理圖為主多但零散每個(gè)節(jié)點(diǎn)一個(gè)完整小程序反饋速度慢學(xué)完未必會(huì)寫慢概念太多快每跑通一個(gè)都有正反饋?zhàn)罱K目標(biāo)理解原理使用框架理解主鏈路并具備擴(kuò)展基礎(chǔ)適合人群想深入原理的研究者已有應(yīng)用經(jīng)驗(yàn)的開發(fā)者剛?cè)腴T應(yīng)用開發(fā)的工程師這個(gè)定位非常關(guān)鍵。如果你現(xiàn)在最需要的是快速建立對(duì) LLM 應(yīng)用開發(fā)的整體認(rèn)知并且希望每一步都有代碼可跑那么這類項(xiàng)目比純理論書和純框架文檔都更適合你。3. LLM 應(yīng)用開發(fā)的核心概念先分清幾個(gè)關(guān)鍵詞在動(dòng)手之前先花一點(diǎn)時(shí)間把后面代碼里會(huì)反復(fù)出現(xiàn)的幾個(gè)概念講清楚。這些詞不是拿來(lái)背的是拿來(lái)對(duì)應(yīng)代碼的。第一個(gè)是 Chat Completion API。這是目前大模型應(yīng)用開發(fā)最常用的接口形態(tài)。你傳一個(gè)消息列表給它它返回模型生成的文本。消息列表里每條消息都帶角色通常有 system、user、assistant 三種。system 負(fù)責(zé)設(shè)定模型身份和行為邊界user 是用戶輸入assistant 是模型歷史回復(fù)。多輪對(duì)話就是不斷往這個(gè)列表里追加消息。第二個(gè)是 Token。Token 是模型處理文本的最小單位可以粗略理解成“模型眼里的單詞碎片”。文本長(zhǎng)度、上下文窗口、計(jì)費(fèi)都以 Token 計(jì)算。你傳入的 messages 和模型輸出的完整內(nèi)容總 Token 數(shù)不能超過(guò)模型的上下文窗口。第三個(gè)是 Temperature。它控制輸出的隨機(jī)性數(shù)值越高回答越發(fā)散越低越確定。需要穩(wěn)定解析結(jié)果時(shí)通常設(shè)置低一些需要?jiǎng)?chuàng)意文案時(shí)可以設(shè)高一些。第四個(gè)是 Embedding。它把一段文本轉(zhuǎn)換成一個(gè)高維向量讓語(yǔ)義相近的文本在向量空間里距離更近。RAG 里的“檢索”本質(zhì)上就是計(jì)算用戶問(wèn)題和文檔向量之間的相似度。第五個(gè)是 Function Calling。它是讓模型具備“行動(dòng)能力”的關(guān)鍵。你在請(qǐng)求里聲明一個(gè)函數(shù)的結(jié)構(gòu)模型判斷需要調(diào)用它時(shí)會(huì)返回結(jié)構(gòu)化的調(diào)用參數(shù)由你的代碼真正執(zhí)行函數(shù)再把結(jié)果回傳給模型生成最終回答。第六個(gè)是 RAG。RAG 全稱是 Retrieval-Augmented Generation檢索增強(qiáng)生成。核心思路是外部文檔切分成塊向量化后存入向量數(shù)據(jù)庫(kù)用戶提問(wèn)時(shí)先檢索相關(guān)內(nèi)容再把檢索結(jié)果和問(wèn)題一起拼進(jìn)提示詞讓模型基于參考材料回答。它解決的是模型不懂私有知識(shí)、知識(shí)更新成本高、容易產(chǎn)生幻覺(jué)的問(wèn)題。這些概念可以用一張表映射到傳統(tǒng)軟件工程LLM 應(yīng)用概念傳統(tǒng)軟件類比核心作用system prompt配置中心控制行為邊界messages請(qǐng)求參數(shù)傳遞會(huì)話上下文結(jié)構(gòu)化輸出接口契約讓文本可被程序解析Embedding索引把文本變成可計(jì)算語(yǔ)義距離的數(shù)據(jù)Function CallingAPI 網(wǎng)關(guān)讓模型觸發(fā)真實(shí)操作RAG外部數(shù)據(jù)源查詢補(bǔ)充模型不知道的知識(shí)理解了這些映射后面寫代碼時(shí)就不會(huì)覺(jué)得大模型應(yīng)用開發(fā)是另一套完全陌生的東西。它就是“模型做語(yǔ)義理解和決策代碼做確定性的計(jì)算和 IO”的結(jié)合。4. 環(huán)境準(zhǔn)備與前置條件開始寫代碼之前先把環(huán)境準(zhǔn)備好。這里不會(huì)寫死版本號(hào)因?yàn)椴煌瑫r(shí)間安裝的依賴版本會(huì)有差異但整體思路是通用的。建議使用 Python 3.9 或更高版本。如果你本地已經(jīng)裝了 Anaconda 或者 Miniconda可以直接用 conda 創(chuàng)建一個(gè)新環(huán)境如果習(xí)慣用原生 Python用 venv 也足夠。python -m venv llm_env source llm_env/bin/activate # Windows 下使用 llm_env\Scripts\activate然后安裝核心依賴。這里以 OpenAI SDK 為例國(guó)內(nèi)很多大模型服務(wù)商都提供 OpenAI 兼容接口所以代碼結(jié)構(gòu)可以復(fù)用只需要換 base_url 和 api_key。pip install openai python-dotenv numpy gradio把這些依賴寫入requirements.txt也方便后續(xù)重建環(huán)境openai1.0 python-dotenv1.0 numpy1.24 gradio4.0接下來(lái)需要準(zhǔn)備一個(gè) API Key。如果你是第一次接觸優(yōu)先使用你所在環(huán)境容易訪問(wèn)的模型服務(wù)商。注冊(cè)后創(chuàng)建 Key填入項(xiàng)目根目錄下的.env文件LLM_API_KEY你的_API_KEY LLM_BASE_URLhttps://api.openai.com/v1 LLM_MODELgpt-4o-mini EMBEDDING_MODELtext-embedding-ada-002這里強(qiáng)烈建議使用.env文件管理密鑰而不是把 Key 硬編碼在代碼里。后續(xù)涉及任何分享代碼的場(chǎng)景硬編碼 Key 都是高危行為。代碼結(jié)構(gòu)上建議按主題分成獨(dú)立文件不要把所有代碼堆在一個(gè)腳本里。參考結(jié)構(gòu)如下happy-llm-practice/ ├── .env ├── requirements.txt ├── 01_basic_chat.py ├── 02_structured_output.py ├── 03_stream_chat.py ├── 04_rag_demo.py ├── 05_agent_demo.py └── 06_web_demo.py每個(gè)文件都是一個(gè)可以獨(dú)立運(yùn)行的最小示例這本身就是 happy-llm 提倡的學(xué)習(xí)方式一次只關(guān)注一個(gè)知識(shí)點(diǎn)跑通了再進(jìn)下一個(gè)。5. 第一個(gè) LLM 小程序API 調(diào)用與基礎(chǔ)對(duì)話從最簡(jiǎn)單的程序開始。新建01_basic_chat.py先實(shí)現(xiàn)一次最基本的對(duì)話補(bǔ)全。# 文件路徑happy-llm-practice/01_basic_chat.py import os from openai import OpenAI from dotenv import load_dotenv load_dotenv() client OpenAI( api_keyos.getenv(LLM_API_KEY), base_urlos.getenv(LLM_BASE_URL) ) response client.chat.completions.create( modelos.getenv(LLM_MODEL), messages[ {role: system, content: 你是一個(gè)樂(lè)于助人的中文助手。}, {role: user, content: 用一句話解釋什么是大語(yǔ)言模型。} ], temperature0.7 ) print(response.choices[0].message.content)這段代碼做了三件事讀取環(huán)境變量、初始化客戶端、發(fā)起一次對(duì)話請(qǐng)求。注意messages是一個(gè)列表列表里是消息字典。system 消息用來(lái)約束模型行為user 消息是用戶提問(wèn)。這是 LLM 應(yīng)用開發(fā)最核心的數(shù)據(jù)結(jié)構(gòu)后面所有復(fù)雜功能本質(zhì)上都在圍繞這個(gè)列表做文章。運(yùn)行方式很簡(jiǎn)單python 01_basic_chat.py如果一切正常會(huì)看到一行模型生成的回答。如果出現(xiàn)401說(shuō)明 API Key 不正確如果出現(xiàn)超時(shí)檢查 base_url 和網(wǎng)絡(luò)連通性如果提示模型不存在檢查環(huán)境變量里的模型名是否和服務(wù)商提供的一致。這里有一個(gè)初學(xué)者容易忽略的點(diǎn)response是一個(gè)結(jié)構(gòu)化的響應(yīng)對(duì)象不是純文本。.choices[0].message.content才是最終文字內(nèi)容。理解和熟悉這個(gè)響應(yīng)結(jié)構(gòu)比背文檔更有用因?yàn)楹竺孀隽魇捷敵觥⒐ぞ哒{(diào)用時(shí)都要操作這個(gè)結(jié)構(gòu)。6. 工程化第一步結(jié)構(gòu)化輸出、流式輸出與多輪對(duì)話能完成一次基礎(chǔ)對(duì)話之后接下來(lái)要把“模型聊天能力”工程化。這就要處理三個(gè)問(wèn)題模型輸出怎么被程序穩(wěn)定解析用戶體驗(yàn)怎么更流暢多輪對(duì)話的上下文怎么管理。6.1 結(jié)構(gòu)化輸出模型返回的是自然語(yǔ)言文本但程序需要的是 JSON、字典、列表這類結(jié)構(gòu)。比如做一個(gè)信息抽取功能你希望模型返回“公司名、金額、日期”而不是一段口語(yǔ)化描述。解決方案就是結(jié)構(gòu)化輸出?，F(xiàn)在不少模型服務(wù)商支持response_format參數(shù)# 文件路徑happy-llm-practice/02_structured_output.py import os import json from openai import OpenAI from dotenv import load_dotenv load_dotenv() client OpenAI( api_keyos.getenv(LLM_API_KEY), base_urlos.getenv(LLM_BASE_URL) ) response client.chat.completions.create( modelos.getenv(LLM_MODEL), response_format{type: json_object}, messages[ {role: system, content: 你是信息抽取助手。只輸出嚴(yán)格 JSON不要輸出任何解釋。}, {role: user, content: 從這句話中抽取公司名稱和融資金額北京某科技公司宣布完成 5000 萬(wàn)元 A 輪融資。 輸出格式{\company\: \\, \amount\: \\}} ] ) content response.choices[0].message.content data json.loads(content) print(data[company], data[amount])這里真正容易踩坑的地方是JSON 解析失敗。模型偶爾會(huì)輸出多行解釋或者把 JSON 包在代碼塊標(biāo)記里。穩(wěn)妥做法是在 system 消息里反復(fù)強(qiáng)調(diào)“只輸出嚴(yán)格 JSON”并在解析時(shí)加入異常處理失敗就重試一次。如果服務(wù)商不支持response_format參數(shù)退而求其次也可以用強(qiáng)約束的提示詞來(lái)引導(dǎo)輸出格式再配合正則或字符串清理來(lái)做兜底。6.2 流式輸出普通請(qǐng)求要等模型把完整內(nèi)容生成完才返回體驗(yàn)上像卡頓。流式輸出可以邊生成邊推送讓用戶看到逐字出現(xiàn)的效果。代碼改動(dòng)很小# 文件路徑happy-llm-practice/03_stream_chat.py import os from openai import OpenAI from dotenv import load_dotenv load_dotenv() client OpenAI( api_keyos.getenv(LLM_API_KEY), base_urlos.getenv(LLM_BASE_URL) ) stream client.chat.completions.create( modelos.getenv(LLM_MODEL), messages[{role: user, content: 寫一段關(guān)于學(xué)習(xí)大語(yǔ)言模型應(yīng)用開發(fā)的 50 字總結(jié)。}], streamTrue ) for chunk in stream: delta chunk.choices[0].delta if delta and delta.content: print(delta.content, end, flushTrue)對(duì)比普通請(qǐng)求這里只是加了streamTrue然后遍歷返回的 chunk。生產(chǎn)環(huán)境中流式輸出還要考慮客戶端連接斷開、超時(shí)中斷等情況但作為學(xué)習(xí)項(xiàng)目跑通這個(gè)最小示例就足夠了。6.3 多輪對(duì)話與上下文管理大模型 API 本身是無(wú)狀態(tài)的。第二次請(qǐng)求時(shí)模型不會(huì)記得第一次請(qǐng)求說(shuō)了什么。所謂“多輪對(duì)話”其實(shí)是把歷史消息重新全部傳給模型。history [ {role: system, content: 你是一個(gè)中文助手。} ] def chat_with_history(user_input): history.append({role: user, content: user_input}) response client.chat.completions.create( modelos.getenv(LLM_MODEL), messageshistory ) answer response.choices[0].message.content history.append({role: assistant, content: answer}) return answer每次對(duì)話把整個(gè)history數(shù)組傳給模型。這就是為什么上下文窗口很重要?dú)v史越長(zhǎng)消耗的 Token 越多早晚會(huì)超出模型的窗口限制。工程上常用兩種策略一是滑動(dòng)窗口只保留最近 N 條消息二是對(duì)歷史做摘要把早期對(duì)話壓縮成一段概述。至于是不是需要引入專門的消息存儲(chǔ)取決于你的真實(shí)業(yè)務(wù)場(chǎng)景。7. RAG 開發(fā)實(shí)戰(zhàn)讓模型擁有私有知識(shí)模型是在某個(gè)時(shí)間點(diǎn)訓(xùn)練完成的它不知道你公司的內(nèi)部文檔、最新政策、私有產(chǎn)品手冊(cè)。RAG 是目前解決這類問(wèn)題的主流方案。它的核心流程是外部文檔切分成塊 - 每塊文本做向量化 - 向量存入向量數(shù)據(jù)庫(kù)或索引 - 用戶提問(wèn)時(shí)檢索最相關(guān)的若干塊 - 把檢索結(jié)果拼進(jìn)提示詞。下面用一個(gè)最小示例演示完整鏈路。為了不引入額外框架這里直接用 OpenAI 的 Embedding 接口和 NumPy 做相似度計(jì)算。生產(chǎn)環(huán)境請(qǐng)換成真正的向量數(shù)據(jù)庫(kù)但學(xué)習(xí)階段跑通這個(gè)例子更重要。# 文件路徑happy-llm-practice/04_rag_demo.py import os import numpy as np from openai import OpenAI from dotenv import load_dotenv load_dotenv() client OpenAI( api_keyos.getenv(LLM_API_KEY), base_urlos.getenv(LLM_BASE_URL) ) documents [ HAPPY-LLM 是由 Datawhale 社區(qū)維護(hù)的開源學(xué)習(xí)項(xiàng)目。, 它強(qiáng)調(diào)每天一小時(shí)從最小可運(yùn)行代碼開始學(xué)習(xí)大模型應(yīng)用開發(fā)。, RAG 通過(guò)檢索外部知識(shí)來(lái)增強(qiáng)模型的回答能力。, Agent 通過(guò) Function Calling 讓模型具備調(diào)用外部工具的能力。, 多輪對(duì)話需要自行維護(hù)歷史消息列表。 ] def get_embedding(text): resp client.embeddings.create( modelos.getenv(EMBEDDING_MODEL), input[text] ) return resp.data[0].embedding doc_vectors [get_embedding(doc) for doc in documents] def search(query, top_k2): q_vec get_embedding(query) scores [] for i, doc_vec in enumerate(doc_vectors): score float(np.dot(q_vec, doc_vec) / (np.linalg.norm(q_vec) * np.linalg.norm(doc_vec))) scores.append((score, i)) scores.sort(reverseTrue) return [documents[i] for _, i in scores[:top_k]] query 我該怎么學(xué)習(xí)大模型應(yīng)用開發(fā) related search(query) context \n.join(related) prompt f請(qǐng)根據(jù)以下參考資料回答用戶問(wèn)題。 參考資料 {context} 用戶問(wèn)題{query} 如果參考資料不足以回答問(wèn)題請(qǐng)直接說(shuō)明。 response client.chat.completions.create( modelos.getenv(LLM_MODEL), messages[{role: user, content: prompt}] ) print(檢索到的資料) for doc in related: print(-, doc) print(\n模型回答) print(response.choices[0].message.content)這段代碼的核心是search函數(shù)。它把用戶問(wèn)題轉(zhuǎn)換成向量和每條文檔向量計(jì)算余弦相似度取最相似的兩條作為上下文。真正影響 RAG 效果的關(guān)鍵點(diǎn)有兩個(gè)。第一是文檔切分。切得太碎每塊語(yǔ)義不完整切得太大檢索出來(lái)噪音多還浪費(fèi) Token。第二是檢索質(zhì)量。向量相似度并不總是語(yǔ)義相關(guān)有時(shí)候需要加入重排環(huán)節(jié)。學(xué)習(xí)階段先用最樸素的方案跑通理解全流程再逐步引入更高級(jí)的預(yù)處理和檢索策略。這個(gè)例子也解釋了為什么 happy-llm 這類項(xiàng)目強(qiáng)調(diào)“最小可運(yùn)行”RAG 本身不是一個(gè)函數(shù)而是一條數(shù)據(jù)鏈路。如果不從頭到尾親手走一遍只靠讀文檔很難真正理解“切分 - 向量化 - 檢索 - 注入”之間的因果關(guān)系。8. Agent 與 Function Calling從“回答問(wèn)題”到“執(zhí)行任務(wù)”對(duì)話能力和知識(shí)庫(kù)問(wèn)答本質(zhì)還是“回答問(wèn)題”。但很多應(yīng)用場(chǎng)景需要的是“執(zhí)行任務(wù)”用戶問(wèn)“北京今天天氣怎么樣”你需要先去查天氣接口再組織語(yǔ)言回答。模型本身不聯(lián)網(wǎng)、不執(zhí)行代碼所以需要一套機(jī)制讓模型調(diào)用外部工具。這個(gè)機(jī)制就是 Function Calling。過(guò)程可以拆成四步第一步在請(qǐng)求里聲明工具函數(shù)的結(jié)構(gòu)。第二步模型判斷需要調(diào)用工具時(shí)返回一個(gè)tool_calls對(duì)象包含函數(shù)名和參數(shù)。第三步你的代碼真正執(zhí)行這個(gè)函數(shù)拿到結(jié)果。第四步把工具結(jié)果以roletool的消息追加到 messages再讓模型基于工具結(jié)果生成最終回答。下面用一個(gè)查詢天氣的最小示例演示。真實(shí)項(xiàng)目中函數(shù)體內(nèi)部應(yīng)該是請(qǐng)求天氣服務(wù) API這里用本地返回模擬。# 文件路徑happy-llm-practice/05_agent_demo.py import os import json from openai import OpenAI from dotenv import load_dotenv load_dotenv() client OpenAI( api_keyos.getenv(LLM_API_KEY), base_urlos.getenv(LLM_BASE_URL) ) def get_weather(city: str) - str: # 實(shí)際項(xiàng)目中在這里調(diào)用天氣服務(wù) API return f{city} 今天多云氣溫 22 攝氏度。 tools [ { type: function, function: { name: get_weather, description: 查詢指定城市的實(shí)時(shí)天氣, parameters: { type: object, properties: { city: { type: string, description: 城市名例如 北京 } }, required: [city] } } } ] messages [ {role: user, content: 你好請(qǐng)問(wèn)北京今天天氣怎么樣} ] response client.chat.completions.create( modelos.getenv(LLM_MODEL), messagesmessages, toolstools, tool_choiceauto ) msg response.choices[0].message if msg.tool_calls: # 模型決定調(diào)用工具 call msg.tool_calls[0] print(模型要求調(diào)用工具, call.function.name) print(工具參數(shù), call.function.arguments) args json.loads(call.function.arguments) result get_weather(args[city]) # 把工具結(jié)果回傳給模型 messages.append(msg) messages.append({ role: tool, tool_call_id: call.id, content: result }) final_response client.chat.completions.create( modelos.getenv(LLM_MODEL), messagesmessages, toolstools ) print(最終回答, final_response.choices[0].message.content) else: print(模型直接回答, msg.content)這段代碼體現(xiàn)了 Agent 的雛形模型負(fù)責(zé)理解意圖、決定調(diào)用哪個(gè)工具、生成傳給工具的參數(shù)外部代碼負(fù)責(zé)真正執(zhí)行。模型的角色更像是一個(gè)路由器或編排器而不是答案的來(lái)源。初學(xué)者最容易忽略的是工具結(jié)果的回傳格式。tool_call_id必須和模型返回的call.id保持一致否則模型無(wú)法把工具結(jié)果和之前的請(qǐng)求關(guān)聯(lián)起來(lái)。Agent 應(yīng)用開發(fā)真正復(fù)雜的地方在于循環(huán)控制。一個(gè)任務(wù)可能需要連續(xù)調(diào)用多個(gè)工具每次調(diào)用結(jié)果都會(huì)改變后續(xù)步驟。生產(chǎn)環(huán)境還需要考慮設(shè)置最大工具調(diào)用輪數(shù)防止死循環(huán)對(duì)工具輸入做校驗(yàn)對(duì)工具異常做兜底確保工具權(quán)限最小化。所有這些都是 Agent 從 Demo 走向可用的必經(jīng)之路。9. 用 Gradio 把腳本變成 Web 應(yīng)用學(xué)習(xí)到這里你已經(jīng)掌握了 API 調(diào)用、結(jié)構(gòu)化輸出、RAG、工具調(diào)用這幾塊能力但都是在命令行里跑。要讓一個(gè)非技術(shù)的同事或者朋友也能體驗(yàn)可以做一個(gè) Web 頁(yè)面。Gradio 是目前非常方便的工具幾行代碼就能搭出一個(gè)可交互界面。# 文件路徑happy-llm-practice/06_web_demo.py import os import gradio as gr from openai import OpenAI from dotenv import load_dotenv load_dotenv() client OpenAI( api_keyos.getenv(LLM_API_KEY), base_urlos.getenv(LLM_BASE_URL) ) def chat(message, history): history history or [] messages [{role: system, content: 你是一個(gè)友好的人工智能助手。}] for user_msg, assistant_msg in history: messages.append({role: user, content: user_msg}) messages.append({role: assistant, content: assistant_msg}) messages.append({role: user, content: message}) response client.chat.completions.create( modelos.getenv(LLM_MODEL), messagesmessages ) return response.choices[0].message.content demo gr.ChatInterface(fnchat) demo.launch()運(yùn)行python 06_web_demo.py終端會(huì)輸出一個(gè)本地地址通常是http://127.0.0.1:7860瀏覽器打開即可開始對(duì)話。Gradio 的ChatInterface已經(jīng)幫你處理了歷史消息的展示和記錄你只需要關(guān)心如何調(diào)用模型。這個(gè)階段的重點(diǎn)不是把界面做得復(fù)雜而是理解從純函數(shù)到 Web 交互中間發(fā)生了什么用戶輸入進(jìn)入回調(diào)函數(shù)函數(shù)調(diào)用模型返回值渲染成界面消息。后面如果再接入前端的聊天組件、記憶持久化、用戶鑒權(quán)都是在同一套邏輯上擴(kuò)展。10. 常見問(wèn)題與排查思路把學(xué)習(xí)過(guò)程中最常遇到的問(wèn)題整理成一張表方便你快速定位。問(wèn)題現(xiàn)象可能原因排查方式解決方案調(diào)用報(bào)401API Key 錯(cuò)誤或失效檢查.env中 Key 是否正確重新生成 Key確認(rèn)環(huán)境變量已加載提示module沒(méi)有ChatCompletionopenai SDK 版本過(guò)舊執(zhí)行pip show openai升級(jí)到 1.x 版本請(qǐng)求超時(shí)base_url 配置錯(cuò)誤或網(wǎng)絡(luò)不可達(dá)單獨(dú)請(qǐng)求服務(wù)商接口測(cè)試連通性修改 base_url或調(diào)整超時(shí)時(shí)間JSON 解析失敗模型輸出了多余文本打印原始 response content增加 system 約束解析失敗時(shí)重試上下文超限歷史消息過(guò)長(zhǎng)查看 Token 消耗做滑動(dòng)窗口截?cái)嗷驓v史摘要RAG 檢索結(jié)果不相關(guān)文檔切分不合理或向量檢索不準(zhǔn)打印檢索命中的文本塊優(yōu)化切分策略增加 top_k嘗試重排Gradio 界面打不開端口被占用或未安裝完整查看終端日志更換端口或升級(jí) gradio 版本工具調(diào)用反復(fù)循環(huán)缺少最大輪數(shù)限制觀察日志中的調(diào)用鏈設(shè)定最大循環(huán)次數(shù)校驗(yàn)工具輸入表格之外再補(bǔ)一個(gè)最重要的原則任何時(shí)候模型返回了你不期望的結(jié)果第一件事都是打印原始響應(yīng)內(nèi)容而不是猜。大模型應(yīng)用的調(diào)試靠的是看真實(shí)輸入輸出而不是靠記憶。11. 最佳實(shí)踐與學(xué)習(xí)路線建議如果你決定沿著 happy-llm 這條路系統(tǒng)學(xué)下去下面幾條建議可以幫你走得更穩(wěn)。第一API Key 永遠(yuǎn)不要硬編碼也永遠(yuǎn)不要提交到 Git 倉(cāng)庫(kù)。.env文件要加入.gitignore。如果密鑰已經(jīng)泄露第一時(shí)間去服務(wù)商后臺(tái)吊銷并重新生成。第二結(jié)構(gòu)化輸出一定要做異常兜底。模型不是數(shù)據(jù)庫(kù)不能保證每次都返回合法 JSON。在實(shí)際項(xiàng)目中需要在解析失敗時(shí)設(shè)計(jì)重試、修正或降級(jí)邏輯。第三RAG 項(xiàng)目先評(píng)估檢索質(zhì)量再優(yōu)化生成效果。很多 RAG 應(yīng)用效果不好問(wèn)題不在模型而在文檔切分不合理、檢索命中的內(nèi)容不相關(guān)。上下文再?gòu)?qiáng)喂進(jìn)去的參考材料是錯(cuò)的回答也不會(huì)對(duì)。第四Agent 工具調(diào)用要設(shè)置邊界。真實(shí)項(xiàng)目里工具背后都是真實(shí)操作。查詢接口還好如果是刪除、寫入、轉(zhuǎn)賬這類敏感操作必須做權(quán)限校驗(yàn)、參數(shù)白名單和人工確認(rèn)機(jī)制。第五學(xué)習(xí)路線上建議遵循“先原生后框架”的順序。先用原生 OpenAI SDK 跑通 API 調(diào)用、結(jié)構(gòu)化輸出、RAG、Function Calling理解每一步在做什么再去看 LangChain 這類框架你會(huì)更容易看懂它的設(shè)計(jì)意圖。反過(guò)來(lái)一上來(lái)就用框架很容易被抽象概念繞暈。第六驗(yàn)證每個(gè)節(jié)點(diǎn)時(shí)不要只打印“運(yùn)行成功”要觀察實(shí)際輸出是否符合預(yù)期。學(xué) LLM 應(yīng)用開發(fā)和傳統(tǒng)開發(fā)的另一個(gè)區(qū)別是模型行為有隨機(jī)性同一個(gè)輸入可能得到不同輸出。所以測(cè)試時(shí)不要只看一次結(jié)果要跑幾次觀察穩(wěn)定性。12. 總結(jié)這篇博客從 LLM 應(yīng)用開發(fā)的真實(shí)痛點(diǎn)出發(fā)圍繞 datawhalechina/happy-llm 這個(gè)開源項(xiàng)目梳理了一條從零到一的學(xué)習(xí)和技術(shù)實(shí)踐路徑基礎(chǔ) API 調(diào)用、結(jié)構(gòu)化輸出、流式輸出、多輪對(duì)話、RAG 檢索增強(qiáng)生成、Agent 工具調(diào)用和 Gradio Web 應(yīng)用。最大的收獲不是記住某個(gè)函數(shù)而是理解 LLM 應(yīng)用開發(fā)的主鏈路模型提供語(yǔ)義理解和生成能力工程代碼負(fù)責(zé)上下文管理、輸出約束、外部檢索和工具執(zhí)行。學(xué)完這一條鏈路再去看任何框架或生產(chǎn)系統(tǒng)都不會(huì)覺(jué)得它們不可理解。建議你現(xiàn)在就照著第 4 章搭好環(huán)境跑通第 5 章的第一個(gè)小程序然后每天只推進(jìn)一到兩個(gè)節(jié)點(diǎn)。這種方式看起來(lái)慢但每一步都有真實(shí)的代碼反饋比收藏幾十篇教程然后在收藏夾里吃灰要有效得多。后面有機(jī)會(huì)可以繼續(xù)深入提示詞技巧、RAG 的重排序與評(píng)估、Agent 多工具協(xié)作、模型微調(diào)以及生產(chǎn)級(jí)部署。LLM 應(yīng)用開發(fā)還在快速演進(jìn)但核心鏈路是穩(wěn)定的值得親手跑一遍。