Note
本文件指的是 Microsoft Foundry（新） 入口網站。
在這個快速入門中，你將使用 Microsoft Foundry 來：
- 建立專案
- 部署模型
- 執行聊天完成
- 建立和執行代理程式
- 將檔案上傳至代理程式
在這個快速入門中，你將使用 Microsoft Foundry 來：
- 建立專案
- 部署模型
- 準備好編碼 - 安裝必要的套件並驗證
- 與模特兒聊天
- 建立專員
- 與代理程式聊天
Microsoft Foundry SDK 提供多種語言版本，包括 Python、Java、TypeScript 和 C#。 此快速入門提供每個語言的指示。
Tip
本文的其餘部分說明如何建立和使用 Foundry 專案。 請參考快速入門：如果你想使用以樞紐為基礎的專案，請開始 使用 Microsoft Foundry（Hub 專案 ）。 我需要哪種類型的專案？
Prerequisites
- 具有有效訂閱的 Azure 帳戶。 如果您沒有，請建立 免費的 Azure 帳戶，其中包含免費試用訂用帳戶。
- 您必須是訂用帳戶的 擁有者 ，才能取得使用專案所需的適當存取控制。
- 安裝必要的語言執行階段、全域工具和 VS Code 延伸模組，如 準備開發環境中所述。
Important
在開始之前，請確保您的開發環境已準備就緒。
本快速入門著重於 案例特定的步驟 ，例如 SDK 安裝、驗證和執行範例程式碼。
建立資源
在入口網站中，您可以探索來自許多不同提供者的豐富尖端模型目錄。 在本教學課程中，搜尋並選取 gpt-4o 模型。
-
登入 Microsoft Foundry。 確定新鑄造廠的開關是關閉的。 這些步驟指的是 Foundry (傳統版)。
如果你正在一個專案中，請在左上角的導覽列中選擇 Microsoft Foundry 以離開該專案。 稍後您將建立一個新的專案。
從登陸頁面或 模型目錄中，選取 gpt-4o （或 gpt-4o-mini）。
選取 [ 使用此模型]。 出現提示時，輸入新的專案名稱，然後選取 [建立]。
檢閱部署名稱，然後選取 [建立]。
然後選取部署類型之後，選取 [連線並部署 ]。
部署之後，從部署頁面選取 [ 在 Playground 中開啟 ]。
您進入聊天遊樂場，模型已預先部署並可供使用。
如果您要建立代理程式，則可以改為 從建立代理程式開始。 步驟類似，但順序不同。 建立專案後，您將到達客服專員遊樂場，而不是聊天遊樂場。
現在您已經有了代理程式，您可以在程式碼或入口網站中與其互動。
你會從 Microsoft Foundry 入口網站開始建立專案並部署模型。 本快速入門使用 gpt-4-1-mini 模型，但您可以使用數個提供者提供的任何支援模型。
- 登入 Microsoft Foundry。 確定新鑄造廠的開關是關閉的。 這些步驟指的是Foundry (classic)。
登入 Microsoft Foundry。 確定 新 Foundry 的開關是開啟的。 這些步驟指的是 Foundry（新）。
- 項目有助於組織您的工作。 你正在處理的專案會顯示在左上角。
- 若要建立新專案，請選取專案名稱，然後選取 [建立新專案]。
- 為您的專案命名，然後選取 建立專案。
- 現在將模型部署到專案中：
- 選取右上角導覽中的 探索 。
- 選取 [模型]。
- 搜尋 gpt-4.1-mini 模型。
- 選擇部署預設設定（ Deploy>Default settings ）來加入你的專案。
Foundry Models 讓客戶能利用單一端點與憑證，使用旗艦模型供應商最強大的模型。 這表示您可以在模型之間切換，並從您的應用程式取用它們，而不需要變更單行程序代碼。
您現在已準備好繼續與您的模型互動並建立代理程式。
準備好編碼
Tip
程式碼使用 Foundry 專案（經典版）API ，且與 Foundry 專案（新）API（預覽版）不相容。 切換至 Foundry（新）文檔，以便於了解 Foundry 專案（新）API（預覽版）。
安裝下列套件：
pip install openai azure-identity azure-ai-projects==1.0.0-
Microsoft Foundry Models 讓客戶能利用單一端點與憑證，使用旗艦模型供應商最強大的模型。 這表示您可以在模型之間切換，並從您的應用程式取用它們，而不需要變更單行程序代碼。
在專案的 [概觀] 區段中複製 Foundry 專案端點。 您馬上就會用到它。
Tip
如果你看不到 Foundry 專案端點，代表你使用的是基於集線器的專案。 （請參閱 項目類型）。 切換至 Foundry 專案，或使用上述步驟建立一個專案。
- 從右上角導覽中選取 [首頁 ]。
- 選取 [ 金鑰] ，然後複製 端點。 您馬上就會用到它。
在執行 Python 腳本之前，請務必先使用 CLI
az login（或az login --use-device-code） 命令登入以驗證。
按照以下說明或取得程式碼：
Important
本文中的程式碼會使用目前處於預覽狀態的套件。 此預覽版本沒有服務等級協定，不建議將其用於生產工作負載。 可能不支援特定功能，或可能已經限制功能。 如需詳細資訊，請參閱 Microsoft Azure 預覽版增補使用條款。
設定環境變數
將端點儲存為環境變數。 此外，請設定這些值以用於指令碼。
-
從歡迎畫面複製您的終端點。 您將在下一個步驟中使用它。
設定這些環境變數以在您的文稿中使用：
AZURE_AI_FOUNDRY_PROJECT_ENDPOINT=<endpoint copied from welcome screen> AZURE_AI_FOUNDRY_AGENT_NAME="MyAgent" AZURE_AI_FOUNDRY_MODEL_DEPLOYMENT_NAME="gpt-4.1-mini"
安裝和驗證
Tip
程式碼使用 Foundry 專案（新）API（預覽版）， 與 Foundry 專案（經典）API 版本不相容。 請切換至 Foundry（經典版）文件 以查看 Foundry 專案（經典版）的 API 版本。
安裝這些套件，包括
azure-ai-projects的預覽版。 此版本使用 Foundry 專案（新）API （預覽版）。pip install azure-ai-projects --pre pip install openai azure-identity python-dotenv在執行 Python 腳本之前，請務必先使用 CLI
az login（或az login --use-device-code） 命令登入以驗證。
按照以下說明或取得程式碼：
與模特兒聊天
聊天完成是 AI 應用程式的基本建置組塊。 使用聊天完成功能，您可以傳送一系列訊息，並從模型取得回應。
Tip
程式碼使用 Foundry 專案（經典版）API ，且與 Foundry 專案（新）API（預覽版）不相容。 切換至 Foundry（新）文檔，以便於了解 Foundry 專案（新）API（預覽版）。
以此程式碼中的 endpoint 取代您的端點：
from azure.ai.projects import AIProjectClient
from azure.identity import DefaultAzureCredential
project = AIProjectClient(
endpoint="https://your-foundry-resource-name.ai.azure.com/api/projects/project-name",
credential=DefaultAzureCredential(),
)
models = project.get_openai_client(api_version="2024-10-21")
response = models.chat.completions.create(
model="gpt-4o",
messages=[
{"role": "system", "content": "You are a helpful writing assistant"},
{"role": "user", "content": "Write me a poem about flowers"},
],
)
print(response.choices[0].message.content)
與模型互動是 AI 應用程式的基本建構區塊。 傳送輸入並接收模型的回應：
Tip
程式碼使用 Foundry 專案（新）API（預覽版）， 與 Foundry 專案（經典）API 版本不相容。 請切換至 Foundry（經典版）文件 以查看 Foundry 專案（經典版）的 API 版本。
import os
from dotenv import load_dotenv
from azure.identity import DefaultAzureCredential
from azure.ai.projects import AIProjectClient
load_dotenv()
print(f"Using AZURE_AI_FOUNDRY_PROJECT_ENDPOINT: {os.environ['AZURE_AI_FOUNDRY_PROJECT_ENDPOINT']}")
print(f"Using AZURE_AI_FOUNDRY_MODEL_DEPLOYMENT_NAME: {os.environ['AZURE_AI_FOUNDRY_MODEL_DEPLOYMENT_NAME']}")
project_client = AIProjectClient(
endpoint=os.environ["AZURE_AI_FOUNDRY_PROJECT_ENDPOINT"],
credential=DefaultAzureCredential(),
)
openai_client = project_client.get_openai_client()
response = openai_client.responses.create(
model=os.environ["AZURE_AI_FOUNDRY_MODEL_DEPLOYMENT_NAME"],
input="What is the size of France in square miles?",
)
print(f"Response output: {response.output_text}")
建立專員
使用您部署的模型建立代理程式。
代理定義核心行為。 一旦創建，它確保用戶互動中的一致響應，而無需每次都重複指令。 您可以隨時更新或刪除代理程式。
Tip
程式碼使用 Foundry 專案（新）API（預覽版）， 與 Foundry 專案（經典）API 版本不相容。 請切換至 Foundry（經典版）文件 以查看 Foundry 專案（經典版）的 API 版本。
import os
from dotenv import load_dotenv
from azure.identity import DefaultAzureCredential
from azure.ai.projects import AIProjectClient
from azure.ai.projects.models import PromptAgentDefinition
load_dotenv()
project_client = AIProjectClient(
endpoint=os.environ["AZURE_AI_FOUNDRY_PROJECT_ENDPOINT"],
credential=DefaultAzureCredential(),
)
agent = project_client.agents.create_version(
agent_name=os.environ["AZURE_AI_FOUNDRY_AGENT_NAME"],
definition=PromptAgentDefinition(
model=os.environ["AZURE_AI_FOUNDRY_MODEL_DEPLOYMENT_NAME"],
instructions="You are a helpful assistant that answers general questions",
),
)
print(f"Agent created (id: {agent.id}, name: {agent.name}, version: {agent.version})")
與代理程式聊天
創建一個代理並與之聊天。
Tip
程式碼使用 Foundry 專案（經典版）API ，且與 Foundry 專案（新）API（預覽版）不相容。 切換至 Foundry（新）文檔，以便於了解 Foundry 專案（新）API（預覽版）。
以此程式碼中的 endpoint 取代您的端點：
from azure.ai.projects import AIProjectClient
from azure.identity import DefaultAzureCredential
from azure.ai.agents.models import ListSortOrder, FilePurpose
project = AIProjectClient(
endpoint="https://your-foundry-resource-name.ai.azure.com/api/projects/project-name",
credential=DefaultAzureCredential(),
)
agent = project.agents.create_agent(
model="gpt-4o",
name="my-agent",
instructions="You are a helpful writing assistant")
thread = project.agents.threads.create()
message = project.agents.messages.create(
thread_id=thread.id,
role="user",
content="Write me a poem about flowers")
run = project.agents.runs.create_and_process(thread_id=thread.id, agent_id=agent.id)
if run.status == "failed":
# Check if you got "Rate limit is exceeded.", then you want to get more quota
print(f"Run failed: {run.last_error}")
# Get messages from the thread
messages = project.agents.messages.list(thread_id=thread.id)
# Get the last message from the sender
messages = project.agents.messages.list(thread_id=thread.id, order=ListSortOrder.ASCENDING)
for message in messages:
if message.run_id == run.id and message.text_messages:
print(f"{message.role}: {message.text_messages[-1].text.value}")
# Delete the agent once done
project.agents.delete_agent(agent.id)
print("Deleted agent")
使用先前建立名為「MyAgent」的代理程式，透過提問及相關的追問來進行互動。 對話會保留這些互動的歷史記錄。
Tip
程式碼使用 Foundry 專案（新）API（預覽版）， 與 Foundry 專案（經典）API 版本不相容。 請切換至 Foundry（經典版）文件 以查看 Foundry 專案（經典版）的 API 版本。
import os
from dotenv import load_dotenv
from azure.identity import DefaultAzureCredential
from azure.ai.projects import AIProjectClient
load_dotenv()
project_client = AIProjectClient(
endpoint=os.environ["AZURE_AI_FOUNDRY_PROJECT_ENDPOINT"],
credential=DefaultAzureCredential(),
)
agent_name = os.environ["AZURE_AI_FOUNDRY_AGENT_NAME"]
openai_client = project_client.get_openai_client()
# Optional Step: Create a conversation to use with the agent
conversation = openai_client.conversations.create()
print(f"Created conversation (id: {conversation.id})")
# Chat with the agent to answer questions
response = openai_client.responses.create(
conversation=conversation.id, #Optional conversation context for multi-turn
extra_body={"agent": {"name": agent_name, "type": "agent_reference"}},
input="What is the size of France in square miles?",
)
print(f"Response output: {response.output_text}")
# Optional Step: Ask a follow-up question in the same conversation
response = openai_client.responses.create(
conversation=conversation.id,
extra_body={"agent": {"name": agent_name, "type": "agent_reference"}},
input="And what is the capital city?",
)
print(f"Response output: {response.output_text}")
將檔案新增至代理程式
代理程式透過使用工具具有強大的功能。 讓我們添加一個文件搜索工具，使我們能夠進行知識檢索。
- 下載 product_info_1.md ，以提供給您的代理程式。
Tip
程式碼使用 Foundry 專案（經典版）API ，且與 Foundry 專案（新）API（預覽版）不相容。 切換至 Foundry（新）文檔，以便於了解 Foundry 專案（新）API（預覽版）。
以此程式碼中的 endpoint 取代您的端點：
from azure.ai.projects import AIProjectClient
from azure.identity import DefaultAzureCredential
from azure.ai.agents.models import ListSortOrder, FileSearchTool
project = AIProjectClient(
endpoint="https://your-foundry-resource-name.ai.azure.com/api/projects/project-name",
credential=DefaultAzureCredential(),
)
# Upload file and create vector store
file = project.agents.files.upload(file_path="./product_info_1.md", purpose=FilePurpose.AGENTS)
vector_store = project.agents.vector_stores.create_and_poll(file_ids=[file.id], name="my_vectorstore")
# Create file search tool and agent
file_search = FileSearchTool(vector_store_ids=[vector_store.id])
agent = project.agents.create_agent(
model="gpt-4o",
name="my-assistant",
instructions="You are a helpful assistant and can search information from uploaded files",
tools=file_search.definitions,
tool_resources=file_search.resources,
)
# Create thread and process user message
thread = project.agents.threads.create()
project.agents.messages.create(thread_id=thread.id, role="user", content="Hello, what Contoso products do you know?")
run = project.agents.runs.create_and_process(thread_id=thread.id, agent_id=agent.id)
# Handle run status
if run.status == "failed":
print(f"Run failed: {run.last_error}")
# Print thread messages
messages = project.agents.messages.list(thread_id=thread.id, order=ListSortOrder.ASCENDING)
for message in messages:
if message.run_id == run.id and message.text_messages:
print(f"{message.role}: {message.text_messages[-1].text.value}")
# Cleanup resources
project.agents.vector_stores.delete(vector_store.id)
project.agents.files.delete(file_id=file.id)
project.agents.delete_agent(agent.id)
清理資源
如果您不再需要您所建立的任何資源，請刪除與您的專案相關聯的資源群組。
在 Microsoft Foundry 入口網站中，請在右上角選擇您的專案名稱。 然後選取資源群組的連結，以在 Azure 入口網站中開啟它。 選取資源群組，然後選取 [ 刪除]。 確認您想要刪除資源群組。
在 Azure 入口網站中，尋找並選取您的資源群組。 選取 [刪除] ，然後確認刪除資源群組及其所有相關聯的資源。