{
 "byKey": {
  "cover": [
   {"say":"大家好,歡迎回到 Linux A I 助理開發實戰。這一章要把 L L M 的 A P I 整合進來。我們會認識 A P I 的基本觀念、學會保管金鑰、用 Python 寫出自己的 L L M 模組,最後處理錯誤和控制成本。","item":0}
  ],
  "LLM API 基礎:messages、token 與常用參數#1": [
   {"say":"我們先建立一個基本觀念,呼叫 L L M 的 A P I,到底是在做什麼?","item":0},
   {"say":"說穿了,它就是一次 H T T P S 請求。你送出一串訊息和一些設定,服務就回傳模型產生的文字,還有這次的用量資訊。","item":1},
   {"say":"OpenAI 官方有提供 Python 的 S D K,這門課用的是它的 Chat Completions 介面。另外還有比較新的 Responses A P I,概念很接近,兩者的差異可以查官方文件。我們聚焦在 Chat Completions,因為大多數相容的服務也都支援。","item":1}
  ],
  "LLM API 基礎:messages、token 與常用參數#2": [
   {"say":"每一則訊息,都有角色和內容兩個部分。角色一共有四種。","item":0},
   {"say":"第一種是 system,用來設定助理的身分、規則和輸出格式,第四章會深入談。","item":1},
   {"say":"第二種是 user,就是使用者輸入的內容。","item":2},
   {"say":"第三種是 assistant,是模型先前的回覆,用來維持多輪的對話。","item":3},
   {"say":"第四種是 tool,放的是工具執行的結果,第五章會用到。","item":4},
   {"say":"要記得,模型本身沒有記憶。多輪對話,靠的是你每一次都把歷史訊息一起送出去。所以歷史越長,花費就越高,也可能超過上下文的上限。","item":4}
  ],
  "LLM API 基礎:messages、token 與常用參數#3": [
   {"say":"我們來看一個實際的訊息串列長什麼樣子。","item":0},
   {"say":"第一則的角色是 system,內容是告訴模型,你是 Linux 維運助理,用繁體中文簡潔回答。","item":1},
   {"say":"第二則的角色是 user,內容是使用者的問題,什麼是 load average。就這樣兩則訊息,就可以送出去了。","item":2}
  ],
  "LLM API 基礎:messages、token 與常用參數#4": [
   {"say":"再來談 token 和費用,這跟你的荷包直接相關。","item":0},
   {"say":"模型是用 token,也就是詞的片段,當作單位來計算輸入和輸出的長度,費用也是照這個算。回應裡的 usage 欄位,會告訴你這次輸入和輸出各用了多少 token。","item":1},
   {"say":"中文通常比英文更耗 token。要控制成本,可以精簡系統提示、截斷日誌、限制輸出長度,還有把舊的對話做成摘要。至於各個模型的上下文長度和價格,會隨時間變動,請以官方文件為準。","item":1}
  ],
  "LLM API 基礎:messages、token 與常用參數#5": [
   {"say":"呼叫 A P I 的時候,有幾個常用的參數。","item":0},
   {"say":"第一個是 model,模型名稱。模型名稱會更新,也會被淘汰,所以請查官方文件的最新名稱,並且放在環境變數裡,不要寫死在程式裡。","item":1},
   {"say":"第二個是 temperature,控制隨機性。維運診斷要的是穩定,建議設低一點,大約零到零點三。不過有些模型可能不支援自訂這個參數。","item":2},
   {"say":"第三個是限制輸出長度的參數。不同的模型,用的參數名稱可能不一樣,一樣要以官方文件為準。","item":3},
   {"say":"第四個是 timeout,是 S D K 這一層的逾時設定。","item":4},
   {"say":"第五個是 stream,決定要不要用串流的方式,一段一段接收回應。","item":5}
  ],
  "LLM API 基礎:messages、token 與常用參數#6": [
   {"say":"這個單元的常見錯誤有四個。","item":0},
   {"say":"第一,把模型名稱寫死,等到模型下架,整個助理就不能用了。","item":1},
   {"say":"第二,以為模型會記得上一次呼叫的內容。其實每一次呼叫都是獨立的。","item":2},
   {"say":"第三,從來不看用量,到了月底才發現費用超出預期。","item":3},
   {"say":"第四,把一整份系統日誌直接丟進去,結果超出上下文長度,呼叫就失敗了。","item":4}
  ],
  "取得與保管 API 金鑰#1": [
   {"say":"第二個單元,我們來談 A P I 金鑰。請把一句話記在心裡,金鑰就是密碼。","item":0},
   {"say":"A P I 金鑰代表的是你帳號的額度。一旦外洩,別人就可以用你的額度發出大量請求,讓你損失費用。","item":1},
   {"say":"所以,金鑰絕對不寫進程式碼,絕對不提交到 git,也絕對不要貼到公開的論壇,或是出現在截圖裡。","item":1}
  ],
  "取得與保管 API 金鑰#2": [
   {"say":"那金鑰要怎麼取得呢?登入 OpenAI 平台的後台,在 A P I keys 的頁面就可以建立。有三個建議。","item":0},
   {"say":"第一,為這個專案建立一把專屬的金鑰,名稱可以直接用專案的名字。","item":1},
   {"say":"第二,在後台設定用量上限,或是預算提醒。這個功能的位置,請查官方文件。","item":2},
   {"say":"第三,金鑰只會顯示一次,拿到之後要馬上存到安全的地方。","item":3}
  ],
  "取得與保管 API 金鑰#3": [
   {"say":"拿到金鑰之後,要怎麼交給程式呢?答案是環境變數。","item":0},
   {"say":"最簡單的方式是用 export 指令,設定兩個環境變數,一個放金鑰,一個放模型名稱。這種設定是暫時的,只對目前這個終端機有效。","item":1},
   {"say":"要注意,這樣打的指令會留在 shell 的歷史紀錄裡。你可以在輸入之前先加一個空白,不過這要看你的歷史紀錄設定。或者,改用下一張要介紹的點 E N V 檔。","item":2}
  ],
  "取得與保管 API 金鑰#4": [
   {"say":"在開發環境裡,比較方便的做法是用點 E N V 檔。","item":0},
   {"say":"在專案的根目錄建立這個檔案,裡面寫兩行,金鑰和模型名稱。接著把檔案權限改成六零零,只有自己能讀寫。再用 git 的 check ignore 指令確認一下,它確實有被忽略。","item":1},
   {"say":"程式這邊,只要從 dotenv 匯入 load dotenv 這個函式,呼叫一次,就會把檔案裡的設定載入成環境變數。","item":2}
  ],
  "取得與保管 API 金鑰#5": [
   {"say":"到了正式環境,做法會再嚴謹一點。","item":0},
   {"say":"用 system D 服務來執行的時候,可以用它的環境檔設定,指向一個放在斜線 E T C 底下的檔案。檔案擁有者設成 root,權限六零零,或是只讓服務帳號可以讀。這部分第十四章會實作。更大型的環境,則會使用專門的機密管理服務。","item":1}
  ],
  "取得與保管 API 金鑰#6": [
   {"say":"萬一金鑰真的外洩了,該怎麼辦?","item":0},
   {"say":"第一步,馬上到後台把這把金鑰撤銷,再重新建立一把。","item":1},
   {"say":"第二步,檢查後台的用量有沒有異常。","item":2},
   {"say":"第三,如果金鑰已經提交進 git,光是把檔案刪掉是不夠的,因為歷史紀錄裡還是看得到。這種情況一律當成已經外洩,直接作廢。","item":3}
  ],
  "取得與保管 API 金鑰#7": [
   {"say":"所以,最好養成提交之前先檢查的習慣。","item":0},
   {"say":"先用 git status 看看有哪些檔案要提交,再把暫存區的差異內容,拿去搜尋有沒有 A P I key 這樣的字眼。也可以用 gitleaks 這類的工具來掃描,安裝方式請參考它的官方文件。","item":1}
  ],
  "以 Python 呼叫 OpenAI API 並封裝 llm.py#1": [
   {"say":"好,第三個單元,開始用 Python 呼叫 A P I。第一步是安裝。","item":0},
   {"say":"在已經啟用的虛擬環境裡,用 pip 安裝 openai 和 python dotenv 這兩個套件,裝完再 freeze 一次,更新套件清單。","item":1}
  ],
  "以 Python 呼叫 OpenAI API 並封裝 llm.py#2": [
   {"say":"我們先寫一個最小的範例,確認可以打通。","item":0},
   {"say":"開頭先匯入 O S 模組,還有 openai 套件裡的 OpenAI 類別。","item":1},
   {"say":"接著建立一個 client,它會自動去讀環境變數裡的金鑰。然後呼叫 chat completions 的 create 方法。","item":2},
   {"say":"傳進去的訊息有兩則,一則是 system,設定它是 Linux 維運助理。另一則是 user,請它用一句話解釋 inode。","item":3},
   {"say":"最後把回覆的文字印出來,再印出這次輸入和輸出各用了多少 token。","item":4},
   {"say":"你會發現,因為 S D K 會自動從環境變數讀金鑰,所以整段程式碼裡,完全看不到金鑰。","item":5}
  ],
  "以 Python 呼叫 OpenAI API 並封裝 llm.py#3": [
   {"say":"我們把 create 裡面的參數,再看清楚一點。","item":0},
   {"say":"第一個參數是 model,它的值是從環境變數讀出來的,不是寫死的。","item":1},
   {"say":"第二個參數是 messages,用一個串列,把剛剛那兩則訊息包起來。","item":2},
   {"say":"串列結束,參數就傳完了。一次最基本的呼叫,其實只需要模型和訊息這兩樣東西。","item":3}
  ],
  "以 Python 呼叫 OpenAI API 並封裝 llm.py#4": [
   {"say":"接下來,把它封裝成 assistant 資料夾裡的 L L M 模組。第一章就規定過,L L M 的呼叫統一放在這裡,讓其他模組不用直接依賴 S D K。這樣寫有四個重點。","item":0},
   {"say":"第一,模型名稱來自環境變數,要換模型,不用改程式。","item":1},
   {"say":"第二,逾時和最大重試次數,S D K 本身就有支援,遇到暫時性的錯誤會自動重試。","item":2},
   {"say":"第三,回傳的是我們自己定義的 L L M Reply。以後要換供應商,只需要改這一個檔案。","item":3},
   {"say":"第四,函式保留了額外的關鍵字參數,讓呼叫的人可以傳入 temperature、回應格式這些設定,第四、第五章會用到。","item":4}
  ],
  "以 Python 呼叫 OpenAI API 並封裝 llm.py#5": [
   {"say":"對照程式碼來看。先看自訂的回覆類別,還有初始化的部分。","item":0},
   {"say":"回覆類別有三個欄位。第一個是 text,存模型回覆的文字。","item":1},
   {"say":"第二個是輸入用掉的 token 數量。","item":2},
   {"say":"第三個是輸出用掉的 token 數量。","item":3},
   {"say":"再來是 client 類別的初始化。它先看有沒有指定模型,沒有就去讀環境變數。兩邊都沒有,就直接報錯,提醒你要設定。最後建立 OpenAI 的 client,逾時設三十秒,最多重試兩次。","item":4}
  ],
  "以 Python 呼叫 OpenAI API 並封裝 llm.py#6": [
   {"say":"然後是最核心的 chat 方法。","item":0},
   {"say":"它接收訊息串列,呼叫 A P I,再把回覆的文字和 token 用量,整理成我們自訂的回覆物件傳回去。如果模型沒有回文字,或是沒有用量資訊,就用空字串和零來代替,程式不會因此出錯。","item":1}
  ],
  "以 Python 呼叫 OpenAI API 並封裝 llm.py#7": [
   {"say":"另外介紹一下串流輸出。","item":0},
   {"say":"串流可以讓使用者先看到一部分的回答,不用等全部產生完,體驗會好很多。做法是在呼叫的時候,把 stream 設成 True。","item":1},
   {"say":"然後用迴圈,一塊一塊地接收,每收到一小段文字就馬上印出來,而且不換行。","item":2},
   {"say":"印之前要先判斷,這一塊裡面到底有沒有內容,有才印,因為有些區塊是空的。","item":3}
  ],
  "錯誤處理、逾時重試與成本控管#1": [
   {"say":"第四個單元,錯誤處理。請先接受一個事實,網路服務一定會有失敗的時候。助理是跑在維運場景裡的,不能因為 A P I 暫時異常就整個當掉。S D K 定義了幾種常用的例外。","item":0},
   {"say":"第一種是認證錯誤,代表金鑰錯了或是失效了,對應的狀態碼是四零一。","item":1},
   {"say":"第二種是速率限制錯誤,代表請求太頻繁,或是額度不夠,狀態碼是四二九。","item":2},
   {"say":"第三種是逾時錯誤。","item":3},
   {"say":"第四種是連線錯誤,也就是網路連不上。","item":4},
   {"say":"第五種是其他的 H T T P 狀態錯誤,包含五開頭的伺服器錯誤,裡面會帶著狀態碼。實際的類別和行為,請以 S D K 的官方文件為準。","item":5}
  ],
  "錯誤處理、逾時重試與成本控管#2": [
   {"say":"我們來看怎麼處理這些錯誤。","item":0},
   {"say":"一開始匯入 logging 和 openai 兩個模組。","item":1},
   {"say":"然後建立一個專門給 L L M 模組用的 logger。","item":2},
   {"say":"接著定義一個叫做 safe chat 的函式,把 L L M 物件和訊息傳進去。","item":3},
   {"say":"正常情況下,它就是直接呼叫 chat,把結果傳回去。","item":4},
   {"say":"如果遇到認證錯誤,就記一筆錯誤紀錄,提醒去檢查金鑰,然後回傳 None,而不是讓程式當掉。","item":5}
  ],
  "錯誤處理、逾時重試與成本控管#3": [
   {"say":"其他幾種錯誤,處理的方式也很類似。","item":0},
   {"say":"遇到速率限制,就記一筆警告,說達到速率或額度的限制,回傳 None。","item":1},
   {"say":"遇到逾時或是連線問題,也是記一筆警告,請使用者稍後再試。","item":2},
   {"say":"其他的狀態錯誤,就把狀態碼記下來。","item":3},
   {"say":"這裡有一個很重要的提醒,紀錄裡不要輸出完整的請求內容,更不能輸出金鑰。","item":4}
  ],
  "錯誤處理、逾時重試與成本控管#4": [
   {"say":"我們把整個結構再整理一次。","item":0},
   {"say":"最外面是一個 try,裡面放正常的呼叫。","item":1},
   {"say":"第一個 except,接的是認證錯誤。","item":2},
   {"say":"第二個 except,接的是速率限制錯誤。每一種錯誤分開接,就可以給出不同的處理和訊息。","item":3}
  ],
  "錯誤處理、逾時重試與成本控管#5": [
   {"say":"後面還有兩個 except。","item":0},
   {"say":"這一個同時接兩種錯誤,逾時和連線失敗,因為它們的處理方式是一樣的。","item":1},
   {"say":"最後一個接的是其他的狀態錯誤,並且把例外物件取個名字,這樣才能讀到裡面的狀態碼。","item":2}
  ],
  "錯誤處理、逾時重試與成本控管#6": [
   {"say":"錯誤發生之後,要不要重試呢?","item":0},
   {"say":"S D K 的最大重試次數設定,會對一部分暫時性的錯誤,自動用退避的方式重試。如果你要自己寫重試,請用指數退避,也就是等一秒、兩秒、四秒這樣拉長,而且要設定次數上限。","item":1},
   {"say":"另外,像四零一這種設定上的錯誤,重試幾次都不會成功,就不應該重試。","item":1}
  ],
  "錯誤處理、逾時重試與成本控管#7": [
   {"say":"最後,給大家一份成本控管的清單。","item":0},
   {"say":"第一,精簡系統提示,避免每一次都送出幾千個字。","item":1},
   {"say":"第二,工具的輸出先截斷或是做摘要。像日誌,只送最近的幾行,或是只送有錯誤的那幾行。","item":2},
   {"say":"第三,限制輸出的長度。","item":3},
   {"say":"第四,歷史對話要設上限。","item":4},
   {"say":"第五,把用量寫進審計紀錄,每天統計。講義裡還有另外三點,在後台設定預算提醒或上限,開發階段先用比較小、比較便宜的模型,還有對相同的問題,可以考慮把結果快取起來。","item":5}
  ],
  "closing": [
   {"say":"好,第三章就到這裡。現在我們的專案已經有一個可以呼叫 L L M 的模組,也知道金鑰要怎麼保管、錯誤要怎麼處理、成本要怎麼控制。","item":0},
   {"say":"請動手把練習做一遍,再完成章末的小測驗,檢查自己學會了多少。我們下一章見。","item":1}
  ]
 }
}
