ai-agents-for-beginners

Thiết lập Khóa học

Giới thiệu

Bài học này sẽ hướng dẫn cách chạy các ví dụ mã trong khóa học này.

Tham gia cùng những người học khác và nhận trợ giúp

Trước khi bạn bắt đầu sao chép repo của mình, hãy tham gia kênh Discord AI Agents For Beginners để nhận trợ giúp về thiết lập, mọi câu hỏi về khóa học, hoặc để kết nối với những người học khác.

Sao chép hoặc Fork repo này

Để bắt đầu, hãy sao chép hoặc fork GitHub Repository. Điều này sẽ tạo phiên bản riêng của bạn của tài liệu khóa học để bạn có thể chạy, kiểm tra và chỉnh sửa mã!

Bạn có thể làm điều này bằng cách nhấp vào liên kết fork the repo

Bạn bây giờ nên có phiên bản repo đã fork của khóa học này tại liên kết sau:

Repo đã fork

Shallow Clone (được khuyến nghị cho workshop / Codespaces)

Toàn bộ repository có thể lớn (~3 GB) khi bạn tải xuống lịch sử đầy đủ và tất cả các tệp. Nếu bạn chỉ tham dự workshop hoặc chỉ cần một vài thư mục bài học, một shallow clone (hoặc sparse clone) tránh phần lớn việc tải xuống đó bằng cách rút ngắn lịch sử và/hoặc bỏ qua các blob.

Quick shallow clone — lịch sử tối thiểu, tất cả các tệp

Thay thế <your-username> trong các lệnh dưới bằng URL fork của bạn (hoặc URL upstream nếu bạn thích).

Để clone chỉ lịch sử commit mới nhất (tải xuống nhỏ):

git clone --depth 1 https://github.com/<your-username>/ai-agents-for-beginners.git

Để clone một nhánh cụ thể:

git clone --depth 1 --branch <branch-name> https://github.com/<your-username>/ai-agents-for-beginners.git

Partial (sparse) clone — blob tối thiểu + chỉ các thư mục được chọn

Điều này sử dụng partial clone và sparse-checkout (yêu cầu Git 2.25+ và khuyến nghị dùng Git hiện đại hỗ trợ partial clone):

git clone --depth 1 --filter=blob:none --sparse https://github.com/<your-username>/ai-agents-for-beginners.git

Đi sâu vào thư mục repo:

cd ai-agents-for-beginners

Sau đó chỉ định các thư mục bạn muốn (ví dụ bên dưới hiển thị hai thư mục):

git sparse-checkout set 00-course-setup 01-intro-to-ai-agents

Sau khi clone và kiểm tra các tệp, nếu bạn chỉ cần các tệp và muốn giải phóng không gian (không còn lịch sử git), hãy xóa metadata của repository (💀không thể phục hồi — bạn sẽ mất toàn bộ chức năng Git: không còn commit, pull, push, hay truy cập lịch sử).

# zsh/bash
rm -rf .git

# PowerShell
Remove-Item -Recurse -Force .git

Sử dụng GitHub Codespaces (khuyến nghị để tránh tải xuống cục bộ lớn)

Mẹo

Chạy Mã

Khóa học này cung cấp một loạt Jupyter Notebooks mà bạn có thể chạy để có trải nghiệm thực hành xây dựng AI Agents.

Các ví dụ mã sử dụng Microsoft Agent Framework (MAF) với AzureAIProjectAgentProvider, kết nối với Azure AI Agent Service V2 (Responses API) thông qua Microsoft Foundry.

Tất cả notebook Python được gán nhãn *-python-agent-framework.ipynb.

Yêu cầu

Chúng tôi đã bao gồm file requirements.txt ở gốc repository này chứa tất cả các gói Python cần thiết để chạy các ví dụ mã.

Bạn có thể cài chúng bằng cách chạy lệnh sau trong terminal tại thư mục gốc của repository:

pip install -r requirements.txt

Chúng tôi khuyến nghị tạo một môi trường ảo Python để tránh xung đột và sự cố.

Thiết lập VSCode

Hãy đảm bảo rằng bạn đang sử dụng đúng phiên bản Python trong VSCode.

hình ảnh

Thiết lập Microsoft Foundry và Azure AI Agent Service

Bước 1: Tạo một Microsoft Foundry Project

Bạn cần một hub và project Azure AI Foundry với một mô hình đã được triển khai để chạy các notebook.

  1. Truy cập ai.azure.com và đăng nhập bằng tài khoản Azure của bạn.
  2. Tạo một hub (hoặc dùng hub đã có). Xem: Hub resources overview.
  3. Bên trong hub, tạo một project.
  4. Triển khai một mô hình (ví dụ gpt-4o) từ Models + Endpoints → Deploy model.

Bước 2: Lấy Endpoint Dự Án và Tên Triển Khai Mô Hình

Từ project của bạn trong cổng Microsoft Foundry:

Chuỗi kết nối dự án

Bước 3: Đăng nhập vào Azure với az login

Tất cả các notebook sử dụng AzureCliCredential để xác thực — không có API key nào phải quản lý. Điều này yêu cầu bạn đăng nhập qua Azure CLI.

  1. Cài đặt Azure CLI nếu bạn chưa: aka.ms/installazurecli

  2. Đăng nhập bằng cách chạy:

     az login

    Hoặc nếu bạn ở môi trường remote/Codespace không có trình duyệt:

     az login --use-device-code

  3. Chọn subscription nếu được nhắc — chọn subscription chứa project Foundry của bạn.

  4. Xác minh bạn đã đăng nhập:

     az account show

Tại sao az login? Các notebook xác thực bằng AzureCliCredential từ package azure-identity. Điều này có nghĩa session Azure CLI của bạn cung cấp thông tin xác thực — không có API key hay secret trong file .env của bạn. Đây là một thực hành bảo mật tốt nhất.

Bước 4: Tạo file .env của bạn

Sao chép file ví dụ:

# zsh/bash
cp .env.example .env

# PowerShell
Copy-Item .env.example .env

Mở .env và điền hai giá trị này:

AZURE_AI_PROJECT_ENDPOINT=https://<your-project>.services.ai.azure.com/api/projects/<your-project-id>
AZURE_AI_MODEL_DEPLOYMENT_NAME=gpt-4o
Variable Where to find it
AZURE_AI_PROJECT_ENDPOINT Foundry portal → your project → Overview page
AZURE_AI_MODEL_DEPLOYMENT_NAME Foundry portal → Models + Endpoints → your deployed model’s name

Chỉ vậy là xong cho hầu hết các bài học! Các notebook sẽ xác thực tự động thông qua session az login của bạn.

Bước 5: Cài các Phụ thuộc Python

pip install -r requirements.txt

Chúng tôi khuyến nghị chạy lệnh này bên trong môi trường ảo bạn đã tạo trước đó.

Thiết lập thêm cho Bài học 5 (Agentic RAG)

Bài học 5 sử dụng Azure AI Search cho retrieval-augmented generation. Nếu bạn dự định chạy bài học đó, thêm các biến này vào file .env của bạn:

Variable Where to find it
AZURE_SEARCH_SERVICE_ENDPOINT Azure portal → your Azure AI Search resource → Overview → URL
AZURE_SEARCH_API_KEY Azure portal → your Azure AI Search resource → Settings → Keys → primary admin key

Thiết lập thêm cho Bài học 6 và Bài học 8 (GitHub Models)

Một số notebook trong bài học 6 và 8 sử dụng GitHub Models thay vì Azure AI Foundry. Nếu bạn dự định chạy những ví dụ đó, thêm các biến này vào file .env của bạn:

Variable Where to find it
GITHUB_TOKEN GitHub → Settings → Developer settings → Personal access tokens
GITHUB_ENDPOINT Use https://models.inference.ai.azure.com (default value)
GITHUB_MODEL_ID Model name to use (e.g. gpt-4o-mini)

Thiết lập thêm cho Bài học 8 (Bing Grounding Workflow)

Notebook workflow có điều kiện trong bài học 8 sử dụng Bing grounding qua Azure AI Foundry. Nếu bạn dự định chạy ví dụ đó, thêm biến này vào file .env của bạn:

Variable Where to find it
BING_CONNECTION_ID Azure AI Foundry portal → your project → Management → Connected resources → your Bing connection → copy the connection ID

Khắc phục sự cố

Lỗi xác thực chứng chỉ SSL trên macOS

Nếu bạn đang dùng macOS và gặp lỗi như:

ssl.SSLCertVerificationError: [SSL: CERTIFICATE_VERIFY_FAILED] certificate verify failed: self-signed certificate in certificate chain

Đây là vấn đề đã biết với Python trên macOS khi các chứng chỉ SSL của hệ thống không được tin cậy tự động. Hãy thử các giải pháp sau theo thứ tự:

Tùy chọn 1: Chạy script Install Certificates của Python (khuyến nghị)

# Thay 3.XX bằng phiên bản Python bạn đã cài đặt (ví dụ: 3.12 hoặc 3.13):
/Applications/Python\ 3.XX/Install\ Certificates.command

Tùy chọn 2: Sử dụng connection_verify=False trong notebook của bạn (chỉ cho các notebook GitHub Models)

Trong notebook Bài 6 (06-building-trustworthy-agents/code_samples/06-system-message-framework.ipynb), một cách khắc phục đã được chú thích sẵn. Bỏ chú thích connection_verify=False khi tạo client:

client = ChatCompletionsClient(
    endpoint=endpoint,
    credential=AzureKeyCredential(token),
    connection_verify=False,  # Vô hiệu hóa việc xác minh SSL nếu bạn gặp lỗi chứng chỉ
)

⚠️ Cảnh báo: Vô hiệu hóa xác thực SSL (connection_verify=False) làm giảm bảo mật bằng cách bỏ qua kiểm tra chứng chỉ. Chỉ sử dụng điều này như một giải pháp tạm thời trong môi trường phát triển, không bao giờ dùng trong sản xuất.

Tùy chọn 3: Cài và sử dụng truststore

pip install truststore

Sau đó thêm đoạn sau ở đầu notebook hoặc script trước khi thực hiện bất kỳ cuộc gọi mạng nào:

import truststore
truststore.inject_into_ssl()

Bị mắc kẹt ở đâu đó?

Nếu bạn có bất kỳ vấn đề nào khi chạy thiết lập này, hãy vào Azure AI Community Discord của chúng tôi hoặc tạo một issue.

Bài học tiếp theo

Bây giờ bạn đã sẵn sàng để chạy mã cho khóa học này. Chúc bạn học vui về thế giới AI Agents!

Giới thiệu về AI Agents và Các trường hợp sử dụng Agent

Tuyên bố miễn trừ trách nhiệm: Tài liệu này đã được dịch bằng dịch vụ dịch thuật AI Co-op Translator (https://github.com/Azure/co-op-translator). Mặc dù chúng tôi nỗ lực đảm bảo độ chính xác, xin lưu ý rằng các bản dịch tự động có thể chứa lỗi hoặc sai sót. Tài liệu gốc bằng ngôn ngữ ban đầu nên được coi là nguồn có thẩm quyền. Đối với thông tin quan trọng, khuyến nghị sử dụng bản dịch chuyên nghiệp do con người thực hiện. Chúng tôi không chịu trách nhiệm về bất kỳ sự hiểu nhầm hoặc diễn giải sai nào phát sinh từ việc sử dụng bản dịch này.

This site is open source. Improve this page.