Foundry Local là bộ runtime AI chạy ngay trên thiết bị do Microsoft phát triển, gồm SDK, danh mục mô hình đã tối ưu và một CLI bản xem trước để thử mô hình bằng dòng lệnh. Bài này tôi bám tài liệu Microsoft Learn cập nhật từ tháng 8 đến tháng 11/2026, hướng dẫn từng bước cài trên Windows và macOS Apple Silicon, dùng lệnh foundry model list để chọn mô hình, kiểm tra execution provider cho CPU, GPU, NPU, quản lý cache và mở API kiểu OpenAI. Nói dễ hiểu, execution provider là thư viện tăng tốc viết riêng cho từng loại chip.
Foundry Local là gì và laptop cần điều kiện nào để cài
Theo trang giới thiệu trên Microsoft Learn, Foundry Local là giải pháp suy luận AI trọn gói, chạy hoàn toàn trên thiết bị. Phần runtime đảm nhận việc tải mô hình, tăng tốc phần cứng, quản lý mô hình và suy luận thông qua ONNX Runtime, chỉ cộng thêm khoảng 20 MB vào gói ứng dụng. Danh mục mô hình được chọn lọc, gồm nhóm chat như GPT OSS, Qwen, DeepSeek, Mistral, Phi và nhóm chuyển giọng nói thành văn bản như Whisper. Mỗi mô hình đều đã qua lượng tử hóa, nén và có số phiên bản.
Microsoft xác định sản phẩm chính là runtime và SDK để nhúng vào ứng dụng, còn CLI và máy chủ web là công cụ đi kèm cho khâu phát triển. CLI đang ở trạng thái public preview, tính năng có thể thay đổi trước khi phát hành chính thức; README trên GitHub dẫn tới bản cli-preview-0.11.0. Tôi đi theo CLI vì đây là cách nhanh để thử mô hình trên laptop, phần SDK chỉ nêu ở mức gọi API cơ bản.
Về nền tảng, phần hỏi đáp ghi Foundry Local hỗ trợ Windows, macOS chạy Apple silicon và Linux, nhưng trang hướng dẫn CLI chỉ có lệnh cài cho Windows và macOS Apple Silicon. Không cần tài khoản Azure, cũng không tốn phí theo token. Điều kiện cần đáp ứng là có Internet ở lần đầu để tải mô hình và execution provider, có quyền quản trị để cài phần mềm, cùng một cửa sổ dòng lệnh như PowerShell hoặc Terminal.
Tài liệu hiện hành không công bố mức RAM hay dung lượng ổ tối thiểu chung, nên tôi không đưa con số nào. Microsoft chỉ khuyên theo dõi mức dùng bộ nhớ khi suy luận để tìm điểm nghẽn, và thử biến thể lượng tử hóa sâu hơn, ví dụ INT8 thay vì FP16. Cách ước lượng RAM, VRAM theo cỡ mô hình được phân tích trong bài Local LLM: Cấu hình RAM và VRAM cho model 7B đến 70B, hữu ích khi cân nhắc cấu hình laptop 16 GB trước lúc nạp mô hình lớn.
Về dữ liệu, prompt và kết quả được xử lý ngay trên thiết bị; mạng chỉ dùng để tải mô hình, thành phần tăng tốc và gửi nhật ký chẩn đoán khi chủ máy chủ động chia sẻ. README lưu ý Foundry Local có thể thu thập dữ liệu sử dụng gửi về Microsoft theo tuyên bố quyền riêng tư. Sau lần tải đầu, mô hình chạy offline từ cache. Laptop lưu mô hình đã tinh chỉnh bằng dữ liệu nhạy cảm nên bật mã hóa ổ đĩa, đây là khuyến nghị bảo mật trong tài liệu.
Cài Foundry Local bằng winget hoặc Homebrew và kiểm tra phiên bản
Trên Windows, việc cài chỉ cần một lệnh, đúng như trang tham chiếu CLI trên Microsoft Learn. Bước 1, mở PowerShell hoặc Windows Terminal bằng tài khoản có quyền quản trị. Bước 2, gõ winget install Microsoft.FoundryLocal rồi nhấn Enter. Kết quả mong đợi là winget tải gói Foundry Local về, cài xong thì báo thành công. Bước 3, mở cửa sổ dòng lệnh mới, gõ foundry --version; màn hình in số phiên bản nghĩa là lệnh foundry đã sẵn sàng.
Trên macOS chạy chip Apple Silicon, tài liệu dùng Homebrew. Bước 1, chạy brew tap microsoft/foundrylocal để thêm kho phần mềm của Microsoft. Bước 2, chạy brew install foundrylocal. Bước 3, kiểm tra bằng foundry --version. Microsoft cũng cho tải tệp .pkg hoặc .zip trong release assets của CLI. Laptop đang dùng bản 0.8.x cần chạy foundry service stop để dừng dịch vụ cũ, rồi mới chạy brew update và brew upgrade.
| Việc cần làm | Windows | macOS Apple Silicon |
|---|---|---|
| Cài đặt | winget install Microsoft.FoundryLocal | brew tap microsoft/foundrylocal, sau đó brew install foundrylocal |
| Kiểm tra phiên bản | foundry --version | foundry --version |
| Nâng cấp | winget upgrade --id Microsoft.FoundryLocal | brew update, sau đó brew upgrade microsoft/foundrylocal/foundrylocal |
| Gỡ cài đặt | winget uninstall Microsoft.FoundryLocal | Tài liệu chưa ghi lệnh |
| Cài thủ công | Add-AppxProvisionedPackage với tệp .msix | Tệp .pkg hoặc .zip trong release assets |
Bước 4, xác nhận dịch vụ nền đã chạy. Gõ foundry --help để in danh sách nhóm lệnh: Model gồm model, cache; Run gồm run, chat, complete, transcribe; Server gồm server; Setup gồm config; Help gồm status, report. Tiếp theo gõ foundry server status. Kết quả mong đợi là màn hình hiện trạng thái daemon, địa chỉ dịch vụ cục bộ, mã tiến trình, thời gian đã chạy và nơi lưu nhật ký. Sau đó gõ thử foundry model list để chắc dịch vụ trả về danh mục.
Lỗi hay gặp ngay sau khi cài là thông báo Request to local service failed, kèm địa chỉ http://127.0.0.1:0/foundry/list và dòng The requested address is not valid in its context. Microsoft giải thích dịch vụ đang chạy nhưng không truy cập được do lỗi gán cổng; cách xử lý là chạy foundry server restart. Lỗi thứ hai xuất hiện khi cài cho mọi tài khoản bằng winget install Microsoft.FoundryLocal --scope machine: winget báo The current system configuration doesn't support the installation of this package, vì winget chặn kiểu cài MSIX phạm vi toàn máy.
Với lỗi phạm vi toàn máy, Bước 1, tải tệp .msix cùng gói phụ thuộc. Bước 2, mở PowerShell bằng quyền Administrator. Bước 3, chạy Add-AppxProvisionedPackage -Online -PackagePath .\FoundryLocal.msix -DependencyPackagePath .\VcLibs.appx -SkipLicense để cài cho mọi tài khoản. Khi cần lên bản mới trên Windows, chạy winget upgrade --id Microsoft.FoundryLocal; khi muốn gỡ, chạy winget uninstall Microsoft.FoundryLocal. Tài liệu hiện chỉ ghi lệnh gỡ cho Windows, chưa có lệnh gỡ riêng cho macOS.
Dùng lệnh foundry model list để chọn mô hình theo phần cứng
Bước 1, gõ foundry model list. Ở lần chạy đầu sau khi cài, Foundry Local tự tải các execution provider hợp với phần cứng của laptop, màn hình hiện thanh tiến trình rồi mới in danh mục. Kết quả mong đợi là bảng liệt kê các mô hình khả dụng trên chính laptop đó. Các gói này chỉ tải lại khi có phiên bản mới, nên lần gõ foundry model list kế tiếp hiện danh sách ngay.
Bước 2, lọc danh sách bằng tùy chọn. Lệnh foundry model list --device gpu chỉ hiện mô hình chạy GPU; giá trị hợp lệ của --device là cpu, gpu và npu. Tùy chọn --type lọc theo tác vụ chat, speech hoặc embedding; --search lọc theo từ khóa, ví dụ foundry model list --search qwen; --cached chỉ hiện mô hình đã tải; --loaded chỉ hiện mô hình đang nạp; --limit giới hạn số dòng. Lệnh foundry model list --verbose thêm cột License, Display Name và Model ID.
Bước 3, phân biệt alias với model ID, vì đây là chỗ quyết định mô hình dùng execution provider nào. Alias là tên ngắn như phi-4-mini hoặc qwen2.5-0.5b; khi gọi bằng alias, Foundry Local ưu tiên biến thể hợp phần cứng, ví dụ laptop có GPU NVIDIA nhận biến thể GPU, laptop có NPU được hỗ trợ nhận biến thể NPU, laptop chip Qualcomm nhận biến thể NPU Qualcomm. Model ID là tên đầy đủ của từng biến thể, ví dụ qwen2.5-0.5b-instruct-generic-cpu luôn chạy trên CPU dù laptop có GPU hay không.
Bước 4, xem thứ tự ưu tiên bằng foundry model list --variants để hiện mọi biến thể của từng alias. Microsoft ghi rõ khi một alias có nhiều biến thể, danh sách xếp theo thứ tự ưu tiên và biến thể ở dòng trên cùng là biến thể sẽ chạy khi gọi bằng alias. Muốn ép laptop chạy NPU hoặc CPU để so hiệu năng, tôi chép đúng model ID của biến thể đó thay vì dùng alias.
Bước 5, xem chi tiết một mô hình trước khi tải bằng foundry model info phi-4-mini. Danh mục REST của CLI mô tả mỗi mô hình có các trường deviceType, executionProvider, fileSizeMb là dung lượng tệp tính bằng MB, supportsToolCalling cho biết có hỗ trợ gọi công cụ hay không, cùng license. Lỗi hay gặp ở bước này là danh sách không hiện vì dịch vụ chưa kết nối; khi đó chạy foundry server restart rồi gõ lại foundry model list.
Execution provider cho CPU, GPU, NPU và driver cần cài trước
Execution provider là thư viện tăng tốc theo từng loại phần cứng, giúp ONNX Runtime chạy mô hình hiệu quả trên thiết bị. Foundry Local tích hợp sẵn ba execution provider. CPU dùng thư viện MLAS, chạy trên mọi CPU và là phương án dự phòng. WebGPU dùng Dawn, chạy trên mọi GPU và là phương án dự phòng cho GPU. CUDA dành cho GPU NVIDIA GeForce RTX 30 series trở lên, driver khuyến nghị tối thiểu 32.0.15.5585 cùng CUDA 12.5.
Trên Windows, các execution provider dạng plugin được tải và đăng ký động tùy thiết bị và driver, rồi tự cập nhật khi có bản mới. Khâu lấy plugin đi qua WinML, nền tảng máy học có sẵn của Windows: WinML lấy plugin hợp phần cứng từ hệ điều hành và Windows Update, đăng ký với ONNX Runtime, đồng thời kiểm tra tương thích driver. Bảng dưới chép yêu cầu từ trang tham chiếu CLI.
| Execution provider | Phần cứng áp dụng | Yêu cầu theo tài liệu |
|---|---|---|
| CPU (MLAS) | Mọi CPU | Tích hợp sẵn, phương án dự phòng |
| WebGPU (Dawn) | Mọi GPU, GPU Apple Silicon qua Metal | Tích hợp sẵn, dự phòng cho GPU |
| CUDA và NvTensorRTRTX | NVIDIA GeForce RTX 30 series trở lên | Driver từ 32.0.15.5585, CUDA 12.5 |
| OpenVINO cho CPU (Intel) | Intel thế hệ 11 (TigerLake) trở lên | Driver từ 32.0.100.9565 |
| OpenVINO cho GPU (Intel) | Intel thế hệ 12 (AlderLake) trở lên | Driver từ 32.0.101.1029 |
| OpenVINO cho NPU (Intel) | Intel thế hệ 15 (ArrowLake) trở lên | Driver từ 32.0.100.4239 |
| QNN (Qualcomm) | NPU Hexagon trên Snapdragon X Elite X1E, X Plus X1P | Driver từ 30.0.140.0 |
| VitisAI (AMD) | NPU AMD | Adrenalin 25.6.3 đến 25.9.1, NPU driver 32.00.0203.280 đến 32.00.0203.297 |
Bước 1, cài driver để kích hoạt tăng tốc NPU trước khi chạy lệnh đầu tiên. Laptop dùng NPU Intel trên Windows cần Intel NPU driver; tài liệu nêu thiếu driver hoặc driver cũ là nguyên nhân NPU Intel không được nhận. Laptop Snapdragon X Elite, X Plus cần driver NPU Qualcomm từ 30.0.140.0. Chỉ số TOPS in trên vỏ hộp không đảm bảo mô hình chạy được trên NPU, khoảng cách này được phân tích trong bài NPU laptop: Quảng cáo chỉ số TOPS và giới hạn thực tế.
Bước 2, chạy foundry model list --device npu. Kết quả mong đợi là danh sách có biến thể NPU; danh sách trống nghĩa là chưa có biến thể NPU cho laptop đó, và theo tài liệu, khi không phát hiện GPU hay NPU, Foundry Local tự chạy bằng CPU. Lỗi NPU Qualcomm hay gặp có mã Qnn error code 5005 kèm dòng Failed to load from EpContext model. Microsoft nêu nguyên nhân là driver NPU Qualcomm cũ hoặc xung đột tài nguyên NPU; cách xử lý là cài driver mới, còn lỗi thì khởi động lại laptop, nhất là sau khi vừa dùng tính năng Copilot+.
Với AMD, tài liệu ghi khoảng hỗ trợ từ Adrenalin Edition 25.6.3 đến 25.9.1, driver ngoài khoảng này chưa có trong danh sách. Trên macOS Apple Silicon, WebGPU chạy qua Dawn, Dawn dịch shader sang Metal Shading Language rồi chạy trên GPU Apple. Có một điểm lệch: bảng phần cứng ở trang kiến trúc chỉ ghi Intel OpenVINO cho GPU, còn trang CLI ghi cả CPU, GPU và NPU, nên tôi giữ yêu cầu theo từng trang. Khi nạp qua REST, tham số ep chọn execution provider, nhận dml, cuda, qnn, cpu hoặc webgpu.
Chạy chat, tải trước mô hình và quản lý bộ nhớ cache
Bước 1, mở phiên chat bằng foundry chat phi-4-mini. Lần đầu, Foundry Local tải mô hình, nạp vào bộ nhớ rồi mở dấu nhắc. Kết quả mong đợi là dấu nhắc nhập liệu xuất hiện; gõ câu hỏi, ví dụ What is the golden ratio?, rồi nhấn Enter để nhận câu trả lời. Bước 2, gõ /exit để kết thúc phiên. Lệnh foundry run qwen2.5-0.5b cũng chạy được mô hình và tự chuyển sang chat hoặc chuyển giọng nói thành văn bản tùy loại mô hình.
Bước 3, khi chỉ cần một câu trả lời, dùng foundry complete kèm tên mô hình và câu lệnh; đây là lệnh sinh văn bản một lần, không giữ ngữ cảnh. Bước 4, muốn chuẩn bị trước khi ra khỏi vùng có mạng, chọn tên từ kết quả foundry model list rồi chạy foundry model download phi-4-mini; mô hình được lưu vào cache mà không chạy. Lệnh foundry model unload gỡ mô hình khỏi daemon nhưng không xóa tệp trên ổ.
Bước 5, kiểm tra cache. Lệnh foundry cache list liệt kê mô hình đã lưu, còn foundry cache location in thư mục cache hiện tại. Bước 6, khi ổ hệ thống đầy, chuyển cache sang ổ dung lượng lớn hơn bằng foundry cache cd kèm đường dẫn thư mục mới. Kết quả mong đợi là chạy lại foundry cache location sẽ thấy đường dẫn vừa đặt.
Bước 7, xóa mô hình không dùng bằng foundry cache remove phi-4-mini. Cần cẩn thận ở lệnh này: bỏ trống tên mô hình thì foundry cache remove xóa toàn bộ mô hình trong cache sau một bước xác nhận; thêm --force thì xóa luôn không hỏi. Với SDK Python, thư mục cache đặt qua tham số model_cache_dir của Configuration.
Lỗi hay gặp ở khâu này là tải mô hình thất bại. Microsoft xếp nguyên nhân vào nhóm kết nối mạng, cách xử lý là kiểm tra Internet rồi chạy foundry cache list để xem mô hình đã vào cache chưa. Khi suy luận chậm, tài liệu gợi ý dừng mọi phiên suy luận của Foundry Toolkit for VS Code trước khi chạy, tận dụng tăng tốc GPU khi có, và thử biến thể lượng tử hóa sâu hơn.
Máy chủ cục bộ, API kiểu OpenAI và cách xử lý lỗi
CLI của Foundry Local chạy một daemon kèm dịch vụ tương thích OpenAI. Bước 1, gõ foundry server start để khởi động. Cổng được cấp động mỗi lần khởi động, nên muốn cố định thì chạy foundry server start --port 39839 --idle-timeout 0; giá trị 0 của --idle-timeout duy trì daemon chạy liên tục, đặt số phút khác thì daemon tự dừng sau chừng ấy phút không hoạt động. Daemon đang chạy thì dùng foundry server restart với cùng tùy chọn. Bước 2, gõ foundry server status để lấy địa chỉ endpoint.
Bước 3, gọi API. Endpoint POST /v1/chat/completions tương thích hoàn toàn với OpenAI Chat Completions API, nhận model, messages, temperature, stream. GET /openai/models trả danh sách mô hình đã cache, GET /openai/loadedmodels trả mô hình đang nạp, GET /openai/status trả endpoint và thư mục chứa mô hình. REST API của CLI đang phát triển, có thể thay đổi không báo trước.
| Lỗi | Nguyên nhân theo Microsoft | Cách xử lý |
|---|---|---|
| Request to local service failed (127.0.0.1:0) | Lỗi gán cổng, dịch vụ không truy cập được | foundry server restart |
| Dịch vụ không khởi động | Xung đột cổng hoặc thiếu quyền | foundry server restart, rồi foundry server logs và foundry report |
| Suy luận chậm | Mô hình nhiều tham số chạy trên CPU | Dùng biến thể tối ưu cho GPU khi có |
| Tải mô hình thất bại | Sự cố kết nối mạng | Kiểm tra Internet, chạy foundry cache list |
| NPU Intel không được nhận | Thiếu hoặc cũ Intel NPU driver | Cài Intel NPU driver cho Windows |
| Qnn error code 5005 | Driver NPU Qualcomm cũ hoặc xung đột NPU | Cài driver mới, khởi động lại laptop |
Bước 4, gọi từ Python. Tài liệu yêu cầu Python 3.11 trở lên, cài bằng pip install foundry-local-sdk openai. Ví dụ mẫu khởi tạo FoundryLocalManager, tải execution provider, lấy mô hình qwen2.5-0.5b, nạp, rồi gọi manager.start_web_service(); base_url lấy từ manager.urls[0] cộng /v1, api_key đặt none, sau đó dùng client.chat.completions.create như với OpenAI. Kết quả mong đợi là câu trả lời in dần trên terminal; lần chạy đầu có thể mất vài phút để tải.
Bước 5, muốn chat trên trình duyệt, chạy foundry run qwen2.5-0.5b, giữ nguyên terminal, lấy cổng bằng foundry server status, rồi mở Open WebUI ở http://localhost:8080. Vào Settings > Admin Settings > Connections, bật Direct Connections; sang Settings > Connections > Manage Direct Connections, bấm dấu cộng, đặt URL http://localhost:PORT/v1, Auth là None, bấm Save. Không thấy mô hình thì chạy lại foundry run rồi tải lại trang.
Khi dịch vụ không khởi động được, hướng dẫn xử lý sự cố của Microsoft nêu nguyên nhân xung đột cổng hoặc thiếu quyền. Bước 1, chạy foundry server restart. Bước 2, còn lỗi thì xem nhật ký bằng foundry server logs; tùy chọn -n đặt số dòng, mặc định 50, còn -f theo dõi dòng mới. Bước 3, chạy foundry status để xem chẩn đoán hệ thống, máy chủ, mô hình, kết nối, rồi foundry report để mở sẵn một issue GitHub kèm thông tin chẩn đoán.
Câu hỏi thường gặp (FAQ)
Foundry Local có miễn phí và cần tài khoản Azure không?
Không cần tài khoản Azure và không tính phí theo token, vì suy luận diễn ra trên thiết bị. SDK dùng giấy phép MIT, CLI theo Microsoft Software License Terms, còn từng mô hình có điều khoản riêng của nhà phát hành.
Laptop không có NPU có chạy được không?
Được. CPU execution provider luôn có sẵn; khi không phát hiện GPU hay NPU, runtime tự chạy bằng CPU. GPU bất kỳ có thể dùng WebGPU, còn GPU NVIDIA RTX 30 series trở lên được hỗ trợ CUDA.
Có tự thêm mô hình từ Hugging Face được không?
Được. Microsoft hướng dẫn dùng Olive để chuyển mô hình Hugging Face dạng Safetensors hoặc PyTorch sang ONNX, cần Python 3.10 trở lên.
Có dùng làm máy chủ cho nhiều người cùng lúc được không?
Microsoft tối ưu runtime cho thiết bị mỗi lần một người sử dụng. Cần phục vụ nhiều người đồng thời, tài liệu khuyên dùng khung suy luận cho máy chủ như vLLM hoặc Triton Inference Server.







Để lại một bình luận