ai-agents-for-beginners

Membina Ejen AI Tempatan Menggunakan Microsoft Foundry Local dan Qwen

Membina Ejen AI Tempatan

Pelajaran sebelum ini menskala ejen ke atas ke awan. Pelajaran ini membawa mereka ke bawah ke satu mesin sahaja. Pada akhirnya, anda akan mempunyai pembantu kejuruteraan yang berfungsi yang membuat alasan, memanggil alat, membaca fail anda, dan mencari dokumentasi anda — tanpa satu panggilan inferens awan pun.

Kenapa anda mahu begitu? Tiga sebab yang selalu muncul dalam kerja kejuruteraan sebenar:

Tangkapannya ialah anda menukar model awan canggih untuk Model Bahasa Kecil (SLM) yang berjalan pada CPU, GPU, atau NPU anda. Pelajaran ini mengenai membina ejen yang baik dalam kekangan itu daripada berpura-pura kekangan itu tidak ada.

Pengenalan

Pelajaran ini akan merangkumi:

Matlamat Pembelajaran

Selepas menamatkan pelajaran ini, anda akan tahu bagaimana untuk:

Prasyarat

Pelajaran ini menganggap anda telah menamatkan pelajaran sebelumnya dan selesa dengan:

Anda juga perlu:

Model Bahasa Kecil: Alat Yang Tepat Untuk Kerja Tempatan

Model awan canggih mempunyai ratusan bilion parameter dan pusat data di belakangnya. SLM mempunyai beberapa bilion parameter dan perlu muat dalam RAM komputer riba anda. Perbezaan itu mewujudkan jangkaan yang jelas.

SLM bagus pada:

SLM lemah pada:

Strategi menang untuk ejen tempatan adalah: biar SLM mengatur, dan biar alat buat kerja berat. Model tidak perlu tahu kod asas anda — ia perlu tahu bila hendak panggil read_file dan search_docs. Ini terus memanfaatkan kekuatan SLM.

flowchart LR
    U[Pembangun] --> A[Ejen SLM Tempatan]
    A -->|memutuskan alat yang mana| T1[baca_fail]
    A -->|memutuskan alat yang mana| T2[cari_dokumen RAG]
    A -->|memutuskan alat yang mana| T3[analisa_kod]
    T1 --> A
    T2 --> A
    T3 --> A
    A --> R[Jawapan, sepenuhnya di peranti]

Microsoft Foundry Local

Microsoft Foundry Local adalah masa jalan ringan yang memuat turun, mengurus, dan menyajikan model sepenuhnya pada mesin anda. Ciri paling penting untuk kami ialah ia mengekspose titik akhir HTTP yang serasi OpenAI — bermakna OpenAI SDK dan klien OpenAI Rangka Kerja Ejen Microsoft berfungsi dengan hanya menukar base_url. Segala yang anda pelajari mengenai membina ejen terus berpindah; hanya titik akhir yang bertukar daripada awan ke localhost.

Foundry Local juga secara automatik memilih binaan model terbaik untuk perkakasan anda — binaan CPU, binaan CUDA/GPU, atau binaan NPU — supaya anda tidak perlu mengoptimumkan mesin demi mesin.

Penyediaan

Pasang Foundry Local (lihat dokumentasi untuk OS anda), kemudian sahkan ia berfungsi:

# Pasang (contoh; ikut dokumen untuk platform anda)
winget install Microsoft.FoundryLocal      # Windows
# brew install microsoft/foundrylocal/foundrylocal   # macOS

# Muat turun dan jalankan model Qwen, kemudian mulakan perkhidmatan tempatan
foundry model run qwen2.5-7b-instruct
foundry service status

Setelah servis berjalan anda mempunyai titik akhir tempatan yang serasi OpenAI (biasanya http://localhost:PORT/v1). Nota menggunakan foundry-local-sdk untuk mengesan titik akhir secara automatik, jadi anda tidak perlu kod keras port.

Panggilan Fungsi Qwen: Kenapa Ia Penting

Ejen adalah ejen hanya jika ia boleh memanggil alat. Ramai SLM boleh berbual tetapi menghasilkan panggilan alat yang tidak boleh dipercayai dan tidak berformat. Model Qwen dilatih untuk panggilan fungsi dan mengeluarkan struktur panggilan alat yang kemas dan konsisten — itulah yang menjadikan model sembang tempatan menjadi ejen tempatan.

Alirannya adalah gelung panggilan alat standard yang anda sudah tahu, cuma berjalan di peranti:

sequenceDiagram
    participant U as Pengguna
    participant A as Ejen Qwen (tempatan)
    participant T as Alat Tempatan
    U->>A: "Apa fungsi auth.py?"
    A->>A: Tentukan: panggil read_file
    A->>T: read_file("auth.py")
    T-->>A: kandungan fail
    A->>A: Fikirkan kandungan
    A-->>U: Penjelasan

RAG Tempatan

Pencarian dokumentasi adalah tempat ejen tempatan memberi nilai. Daripada berharap SLM menghafal dokumen rangka kerja anda, anda menyemat dokumen itu ke dalam pangkalan data vektor tempatan dan biar ejen mengambil potongan relevan bila perlu.

Kami menggunakan Chroma, stor vektor terserap yang berjalan dalam proses tanpa pelayan untuk diurus. Aliran ini sepenuhnya tempatan: model sematan tempatan → vektor tempatan → pengambilan tempatan → SLM tempatan.

flowchart TB
    D[Dokumen / kod anda] --> E[Model penempelan setempat]
    E --> V[(Chroma DB vektor - pada cakera)]
    Q[Pertanyaan ejen] --> QE[Tampal pertanyaan secara setempat]
    QE --> V
    V -->|bahagian top-k| A[Ejen Qwen]
    A --> Ans[Jawapan berasas]

Ini adalah corak Agentic RAG yang sama dari Pelajaran 5 — satu-satunya perbezaan ialah setiap komponen berjalan pada mesin anda.

Pelayan MCP Tempatan

MCP adalah pengangkut, bukan servis awan. Pelayan MCP boleh berjalan sebagai proses tempatan pada stdio, mendedahkan alat kepada ejen anda melalui protokol standard. Ini membolehkan anda menggunakan semula ekosistem pelayan MCP yang semakin berkembang — akses sistem fail, operasi git, kueri pangkalan data — sepenuhnya luar talian.

Postur keselamatan berbeza dari awan, tetapi tidak tiada: pelayan MCP tempatan masih berjalan dengan kebenaran pengguna anda, jadi hadkan skopnya pada apa yang boleh disentuh (direktori projek, bukan keseluruhan folder rumah anda) dan anggap hasilnya sebagai input untuk disahkan.

Corak Hibrid Awan-dan-Tempatan

Utamakan tempatan tidak bermakna hanya tempatan. Sistem matang menghala bergantung pada sensitiviti dan kesukaran:

Situasi Tempat ia berjalan
Kod / data sensitif, atau luar talian SLM Tempatan
Tugas mudah, terhad SLM Tempatan (murah, cepat)
Penalaran multi-lompat sukar pada data tidak sensitif Model Awan
Segalanya, semasa gangguan SLM Tempatan (degradasi lancar)

Ini mencerminkan idea halaan model dari Pelajaran 16 — kecuali salah satu “model” kini adalah mesin anda sendiri. Reka bentuk yang teguh kembali kepada tempatan apabila awan tidak tersedia, jadi ejen merosot kualitinya daripada gagal sama sekali.

flowchart LR
    Q[Permintaan] --> S{Sensitif atau luar talian?}
    S -->|ya| L[SLM Tempatan]
    S -->|tidak| C{Perlukan penalaran mendalam?}
    C -->|tidak| L
    C -->|ya| Cloud[Model awan]
    L --> Out[Respons]
    Cloud --> Out

Makmal Amali: Pembantu Kejuruteraan Tempatan

Buka code_samples/17-local-agent-foundry-local.ipynb dan cuba. Anda akan membina pembantu kejuruteraan tempatan yang berjalan sepenuhnya pada stesen kerja anda dan boleh:

  1. Memanggil alat — melalui panggilan fungsi Qwen melalui Foundry Local.
  2. Melakukan operasi fail tempatan — menyenaraikan dan membaca fail dalam direktori projek.
  3. Menganalisa kod — melaporkan metrik asas pada fail sumber.
  4. Mencari dokumentasi — RAG tempatan ke atas folder dokumen dengan Chroma.
  5. Gunakan MCP — sambung ke pelayan MCP tempatan (dengan langkau sopan jika tiada konfigurasi).

Tiada inferens awan digunakan pada bila-bila masa.

Langkah-Demi-Langkah

Pembantu menyambung ke Foundry Local melalui titik akhir yang serasi OpenAI, jadi kod ejen hampir sama dengan pelajaran awan — hanya klien berubah:

from foundry_local import FoundryLocalManager
from openai import OpenAI

# Foundry Local menemui/muat turun model dan memberikan kami titik akhir tempatan.
manager = FoundryLocalManager(\"qwen2.5-7b-instruct\")
client = OpenAI(base_url=manager.endpoint, api_key=manager.api_key)  # api_key adalah tempat letak tempatan

Alat adalah fungsi Python biasa yang beroperasi dalam skop direktori projek:

def read_file(path: str) -> str:
    \"\"\"Read a file, but only inside the sandboxed project directory.\"\"\"
    full = (PROJECT_ROOT / path).resolve()
    if PROJECT_ROOT not in full.parents and full != PROJECT_ROOT:
        return \"Access denied: path is outside the project directory.\"
    return full.read_text(encoding=\"utf-8\")

Perhatikan pemeriksaan sandbox — walaupun tempatan, alat yang membaca laluan sesuka hati adalah liabiliti. Nota memegang setiap alat dalam skop akar projek sahaja.

Semak Pengetahuan

Uji pemahaman anda sebelum beralih ke tugasan.

1. Berikan dua sebab konkrit untuk menjalankan ejen secara tempatan dan bukan di awan.

Jawapan Mana-mana dua daripada: **privasi** (kod dan data tidak pernah keluar mesin), **kos** (tiada bil inferens per-token), dan **keupayaan luar talian** (berfungsi tanpa rangkaian — di pesawat, di kemudahan selamat, atau semasa gangguan). Sekatan peraturan/pematuhan yang menghalang penghantaran data keluar peranti adalah pendorong biasa untuk sebab privasi.

2. Apakah pembahagian kerja yang disarankan antara SLM dan alatnya dalam ejen tempatan, dan kenapa?

Jawapan Biarkan SLM **mengatur** (menentukan alat mana dipanggil dan dengan argumen apa) dan biarkan **alat buat kerja berat** (membaca fail, mengambil dokumen, mengira keputusan). SLM kuat pada keputusan terhad seperti pemilihan alat tetapi lemah pada pengetahuan luas dan penalaran berbilang lompatan, jadi bergantung pada alat memanfaatkan kekuatan mereka.

3. Apa yang menjadikan kod ejen awan boleh digunakan semula dengan Foundry Local?

Jawapan Foundry Local mendedahkan **titik akhir HTTP yang serasi OpenAI**. OpenAI SDK dan klien OpenAI Rangka Kerja Ejen berfungsi dengannya dengan hanya menukar `base_url` (dan menggunakan kunci API pengganti tempatan). Segalanya tentang kod ejen kekal sama.

4. Kenapa kita gunakan model panggilan fungsi Qwen secara khusus dan bukan SLM lain?

Jawapan Kerana ejen mesti menghasilkan panggilan alat yang boleh dipercayai dan berformat baik. Ramai SLM boleh berbual tetapi menghasilkan struktur panggilan alat yang tidak lengkap atau tidak konsisten. Model Qwen dilatih untuk panggilan fungsi dan menghasilkan panggilan alat yang konsisten, itulah yang menjadikan model sembang tempatan menjadi ejen tempatan yang berfungsi.

5. Dalam salur RAG tempatan, komponen mana yang berjalan pada mesin?

Jawapan Kesemuanya: model sematan, pangkalan data vektor (Chroma, di cakera), langkah pengambilan, dan SLM. Dokumen disemat tempatan, disimpan tempatan, diambil tempatan, dan dianalisis oleh model tempatan — tiada komponen menyentuh awan.

6. Pelayan MCP tempatan berjalan pada mesin anda. Adakah ia secara automatik selamat? Langkah berjaga-jaga apa yang perlu anda ambil?

Jawapan Tidak. Pelayan MCP tempatan berjalan dengan kebenaran pengguna anda, jadi ia boleh mencapai apa sahaja yang anda boleh capai. Hadkan skopnya kepada apa yang diperlukan (contohnya, direktori projek sahaja dan bukan keseluruhan folder rumah anda) dan anggap outputnya sebagai input yang perlu disahkan sebelum bertindak.

7. Terangkan peraturan halaan hibrid yang munasabah yang merangkumi model tempatan.

Jawapan Halakan permintaan sensitif atau luar talian ke SLM tempatan; halakan tugas mudah yang terhad ke SLM tempatan untuk kepantasan dan kos; halakan penalaran multi-lompat sukar pada data tidak sensitif ke model awan; dan kembali kepada SLM tempatan jika awan tidak tersedia supaya ejen merosot secara lancar dan tidak gagal sepenuhnya. Ini adalah halaan model (Pelajaran 16) dengan mesin tempatan sebagai salah satu model.

8. Apakah angka minimum RAM realistik untuk menjalankan ejen tempatan dalam pelajaran ini, dan apa kelebihan lebih RAM?

Jawapan Sekitar **8 GB** adalah minimum realistik; 16 GB+ selesa. Lebih banyak RAM membolehkan anda menjalankan model yang lebih besar dan berupaya serta menyimpan lebih banyak konteks dalam memori. GPU atau NPU mempercepat inferens tetapi tidak wajib — Foundry Local memilih binaan CPU apabila tiada pemecut tersedia.

Tugasan

Kembangkan pembantu kejuruteraan tempatan menjadi penilai dokumentasi tempatan untuk projek kecil pilihan anda (gunakan salah satu folder pelajaran repo ini jika anda mahu).

Penyerahan anda harus:

  1. Indeks folder dokumen/kod sebenar ke Chroma (sekurang-kurangnya lima fail).

  2. Tambah alat find_todos yang mengimbas projek untuk komen TODO/FIXME dan memulangkannya beserta nama fail dan nombor baris — dengan pemeriksaan sandbox sama seperti read_file.

  3. Tanya ejen tiga soalan yang memaksanya untuk menggabungkan alat: satu soalan RAG tulen, satu yang memerlukan membaca fail tertentu, dan satu yang memerlukan mencari TODO.
  4. Ukur masa: masa setiap tiga respons dan catatkan dalam sel markdown. Komen sama ada kelewatan itu boleh diterima untuk aliran kerja yang anda niatkan.

Kemudian tulis satu perenggan pendek mengenai apa yang anda akan alihkan ke awan dan apa yang anda akan simpan secara tempatan untuk penilai ini, dan mengapa. Anda dinilai berdasarkan sama ada komponen tempatan disambungkan dengan betul dan sama ada alasan hibrid anda kukuh — bukan pada kualiti model.

Rumusan

Dalam pelajaran ini anda membina ejen yang berjalan sepenuhnya di mesin anda sendiri:

Ini melengkapkan lengkung penyebaran: Pelajaran 16 mengembangkan ejen ke Microsoft Foundry, dan pelajaran ini mengecilkannya ke atas satu stesen kerja. Pelajaran berikutnya beralih kepada memastikan ejen yang disebarkan selamat.

Sumber Tambahan

Pelajaran Sebelumnya

Menyebarkan Ejen Skala Besar

Pelajaran Seterusnya

Mengamankan Ejen AI

Penafian: Dokumen ini telah diterjemahkan menggunakan perkhidmatan terjemahan AI Co-op Translator. Walaupun kami berusaha untuk ketepatan, sila ambil maklum bahawa terjemahan automatik mungkin mengandungi kesilapan atau ketidaktepatan. Dokumen asal dalam bahasa asalnya harus dianggap sebagai sumber yang sahih. Untuk maklumat penting, terjemahan oleh manusia profesional adalah disyorkan. Kami tidak bertanggungjawab terhadap sebarang salah faham atau salah tafsir yang timbul daripada penggunaan terjemahan ini.

This site is open source. Improve this page.