課程設定

歡迎!在開始用 LangChain.js 打造 AI 應用之前,先把開發環境準備好。這一章會帶你安裝 Node.js、設定 Microsoft Foundry 以取得 AI 模型存取權,並配置專案環境。做完這一課,你就會具備開始用 LangChain.js 開發所需的一切。

先備條件

• 一個 GitHub 帳號(免費)
• 一個 Azure 訂閱(用於 Microsoft Foundry)
• 基本的命令列操作知識
• 文字編輯器或 IDE

📋 你要設定的東西

1. Node.js 與 npm
2. Microsoft Foundry 專案、模型與 API 憑證
3. 專案相依套件
4. 環境變數
5. VS Code(建議使用的 IDE)

---

📖 工作坊比喻

就像做家具前要先把工作坊準備好,開發 AI 應用之前也得先把開發環境準備好。

你會安裝 Node.js、取得 AI 模型的存取權,並配置好工具。這能確保你有穩固的基礎與順暢的開發體驗。來把工作坊準備好吧——只要 15 分鐘!

設定方式

從以下兩種方式中選一種來設定你的開發環境:

1. GitHub Codespaces:使用雲端開發環境。
2. 本機開發:在自己的電腦上設定環境。

不論選 Codespaces 還是本機,接下來都要繼續完成 Microsoft Foundry 設定、.env 配置,以及設定測試。這些步驟兩種方式都必須做。

---

GitHub Codespaces

如果你不想設定本機環境,可以使用 GitHub Codespaces,這是一個在瀏覽器裡運作的雲端開發環境。

1. 建立 Codespace:在 GitHub 上打開 langchainjs-for-beginners,點選綠色的「Code」按鈕,選擇「Open with Codespaces」再選「New codespace」。
2. 等待初始化:環境設定需要一些時間。
3. 開啟終端機:準備好之後,在 Codespaces 裡打開終端機(Terminal > New Terminal)。
4. 繼續下面的步驟:跳過本機安裝 Node.js 與 clone 的步驟,直接前往「設定 Microsoft Foundry」章節,然後配置 .env 並執行設定測試。

---

本機開發

步驟 1:安裝 Node.js

你需要 Node.js LTS(長期支援版) 才能執行 LangChain.js 應用。

檢查 Node.js 是否已安裝:

node --version

如果看到 LTS 版本號(可到 nodejs.org 確認),就沒問題了!直接跳到步驟 2。

安裝 Node.js:

1. 前往 nodejs.org
2. 依照你作業系統的安裝說明操作
3. 驗證安裝結果:

node --version  # 顯示 LTS 版本
npm --version # 顯示 npm 版本

為什麼要用 LTS? 穩定、可用於正式環境,而且會持續收到安全性更新。

---

步驟 2:複製儲存庫

# Clone the course repository
git clone https://github.com/microsoft/langchainjs-for-beginners

# Navigate to the project
cd langchainjs-for-beginners

# Install dependencies
npm install

# Install tsx globally
npm install -g tsx

這會安裝所有必要的套件,包括:

• @langchain/openai —— OpenAI 相容的模型整合(所有章節都會用到)
• @langchain/core —— LangChain 核心功能
• langchain —— 含額外工具的 LangChain 主套件
• dotenv —— 用於管理 API key 的環境變數套件

為什麼要全域安裝 tsx?

tsx 讓你不用先編譯,就能直接執行 .ts 檔案。

比較一下:

# Without tsx: compile then run
tsc myfile.ts && node myfile.js

# With tsx: run directly
tsx myfile.ts

好處:開發更快、流程更簡單,不需要建置步驟。這門課全程都會用 tsx filename.ts 來執行範例程式。

---

設定 Microsoft Foundry

這門課使用 Microsoft Foundry 提供 AI 模型。你可以照著下面的步驟做,或參考 部署 Azure OpenAI 模型快速入門。

雖然這門課是以 Microsoft Foundry 為設計基準,但你也可以使用任何 OpenAI 相容的服務商。如果你選了別的服務商,一樣需要準備好 API key 與端點 URL。

1. 建立 Microsoft Foundry 專案

1. 前往 Microsoft Foundry 入口網站
2. 用你的 Azure 帳號登入
3. 點選 + New project
4. 填寫專案細節:
   • Project name:langchain-course(或你喜歡的名稱)
   • Subscription:選擇你的 Azure 訂閱
   • Resource group:新建或選擇現有的
   • Region:選一個離你近的區域(例如 East US、West Europe)
5. 點選 Create(入口網站會自動建立所需資源)

2. 部署所需的模型

這門課需要部署三個模型:

部署 gpt-5-mini 與 gpt-5(聊天模型):

1. 在你的專案裡,前往左側導覽的 Models + endpoints
2. 點選 + Deploy model → Deploy base model
3. 搜尋並選擇 gpt-5-mini
4. 點選 Confirm
5. 設定部署:
   • Deployment name:gpt-5-mini(保持這個名稱以維持一致性)
   • Model version:選擇最新可用版本
   • Deployment type:Global Standard
   • 點選 Deploy
6. 等待部署完成
7. 以同樣的流程部署 gpt-5。注意如果 gpt-5 沒有立即可用,你可能需要先填表申請存取權限。

[!NOTE]
如果無法部署 gpt-5,可改用 gpt-4.1 作為備援。它在 Microsoft Foundry 中可用,並使用相同的 OpenAI 相容 API。部署名稱請維持 gpt-4.1,並在比較範例中使用這個名稱。

為什麼要部署兩個聊天模型? gpt-5-mini 在課程全程的多數範例中使用(速度較快、成本較低)。gpt-5(若無法使用則改用 gpt-4.1)則用於第 1 章的模型比較練習,藉此展示不同模型之間的效能與能力差異。

部署文字嵌入模型:

1. 再次點選 + Deploy model → Deploy base model
2. 搜尋並選擇 text-embedding-3-small
3. 點選 Confirm
4. 設定部署:
   • Deployment name:text-embedding-3-small(保持這個名稱)
   • Model version:選擇最新可用版本
   • Deployment type:Global Standard
   • 點選 Deploy
5. 等待部署完成

3. 取得你的設定值

部署好模型之後,你需要兩項資訊:

1. API Key:

   • 在你的專案裡,前往左側導覽的 Overview
   • 找到 Endpoints and keys
   • 找到你的 API Key

2. 端點 URL:

   • 找到 Azure OpenAI → Azure OpenAI endpoint 的值(格式類似:https://your-resource.openai.azure.com)

為什麼選 Microsoft Foundry?

• ✅ 可用於正式環境:企業級基礎設施與 SLA
• ✅ 更高的用量上限:每分鐘請求數比免費方案多
• ✅ 額外功能:私有端點、內容過濾、監控
• ✅ Azure 整合:與其他 Azure 服務無縫搭配

---

配置環境變數

建立 .env 檔案:

Mac、Linux、WSL on Windows,或 GitHub Codespaces:

cp .env.example .env

Windows 命令提示字元:

# Windows Command Prompt
copy .env.example .env

# Windows PowerShell
Copy-Item .env.example .env

編輯 .env 檔案:

用你的文字編輯器打開 .env,加入你的 Microsoft Foundry 憑證。記得在端點 URL 結尾加上 /openai/v1。

AI_API_KEY=your_microsoft_foundry_api_key
AI_ENDPOINT=https://your-resource.openai.azure.com/openai/v1
AI_MODEL=gpt-5-mini
AI_EMBEDDING_MODEL=text-embedding-3-small

把 API key 與端點換成你 Microsoft Foundry 專案裡的實際值。

---

測試你的設定

來驗證一切是否正常運作!

執行測試:

在專案根目錄的終端機執行以下指令:

tsx scripts/test-setup.ts

預期輸出:

🚀 Testing AI provider connection...

✅ SUCCESS! Your AI provider is working!
   Provider: https://your-resource.openai.azure.com/openai/v1
   Model: gpt-5-mini

Model response: Setup successful!

🎉 You're ready to start the course!

如果看到這個結果,就代表設定完成了!如果沒有,請查看下方的「疑難排解」章節。

---

安裝 VS Code(建議)

雖然你可以用任何文字編輯器,但我們建議使用 Visual Studio Code 以獲得最佳體驗。如果你使用 GitHub Codespaces,可以跳過這一步。

安裝 VS Code:

1. 前往 code.visualstudio.com
2. 下載對應你作業系統的版本
3. 安裝並啟動 VS Code

✅ 設定檢查清單

開始上課前,請確認你已經:

• 安裝好 Node.js LTS(本機開發),或準備好一個 Codespace
• 若在本機工作,已 clone 專案並安裝相依套件(npm install)
• 若在本機工作,已全域安裝 tsx(npm install -g tsx)
• 已建立 Microsoft Foundry 專案,並部署好 gpt-5-mini、gpt-5 與 text-embedding-3-small
• .env 檔案已配置好你的 Microsoft Foundry API key、端點與模型名稱
• 測試腳本執行成功
• 已安裝 VS Code(選用,但建議本機開發時使用)

---

🐛 疑難排解

問題:「Cannot find module '@langchain/openai'」

解法:在專案目錄下執行 npm install

問題:「AI_API_KEY not found」或「AI_ENDPOINT not found」

解法:

1. 確認專案根目錄有 .env 檔案
2. 檢查 .env 是否包含所有必要變數:
   • AI_API_KEY=your_key
   • AI_ENDPOINT=your_endpoint_url
   • AI_MODEL=gpt-5-mini
   • AI_EMBEDDING_MODEL=text-embedding-3-small
3. 值不需要加引號
4. = 前後不要有空格

問題:「401 Unauthorized」或「Invalid API key」

解法:

1. 從你的 Microsoft Foundry 專案重新複製一組新的 API key
2. 確認你複製了完整的 key
3. 確認 AI_ENDPOINT 結尾有加上 /openai/v1
4. 檢查 .env 檔案裡是否有多餘的空格

問題:速率限制錯誤

解法:Microsoft Foundry 的部署有速率限制。如果碰到限制:

• 等幾分鐘後重試
• 到 Microsoft Foundry 入口網站檢查你的部署配額
• 大部分範例改用 gpt-5-mini,以維持在限制範圍內

---

內容來源:本頁譯自 Microsoft 的開源課程
LangChain.js for Beginners,原文連結:https://github.com/microsoft/langchainjs-for-beginners/blob/main/00-course-setup/README.md

MIT License, Copyright (c) Microsoft Corporation。
本頁為碼力獅社群的中文翻譯與整理(翻譯課文、保留原文的參考資源連結、附上重點整理),
非原作者的官方中文版;內容如與原文有出入,以原文為準。
原課程的程式碼範例、解答與測試腳本請直接使用原始 repo。