foundry-local

环境要求

• Node.js 与 npm（使用 JavaScript SDK 时）
• Python 与 pip（使用 Python SDK 时）
• 本地设备可运行 ONNX Runtime 推理，运行时约 20 MB
• 官方也提供 C#、Rust 语言绑定以及安装包下载

安装与启动步骤

1. 1安装 JS SDK

   在 Node.js 项目中执行安装，包名 foundry-local-sdk，安装后即可在代码中引入 FoundryLocalManager。

   npm install foundry-local-sdk

   复制

2. 2运行 JS 对话示例

   把 README 示例存为 js 文件用 Node 运行；会自动按硬件选择最佳模型变体并下载 qwen2.5-0.5b。

   import { FoundryLocalManager } from 'foundry-local-sdk';
   
   const manager = FoundryLocalManager.create({ appName: 'my-app' });
   
   // Download and load a model (auto-selects best variant for user's hardware)
   const model = await manager.catalog.getModel('qwen2.5-0.5b');
   await model.download((progress) => {
       process.stdout.write(`
   Downloading... ${progress.toFixed(2)}%`);
   });
   await model.load();
   
   // Create a chat client and get a completion
   const chatClient = model.createChatClient();
   const response = await chatClient.completeChat([
       { role: 'user', content: 'What is the golden ratio?' }
   ]);
   
   console.log(response.choices[0]?.message?.content);
   
   // Unload the model when done
   await model.unload();

   复制

3. 3安装 Python SDK

   使用 pip 安装官方 Python 包 foundry-local-sdk，用于在 Python 应用中调用本地模型推理。

   pip install foundry-local-sdk

   复制

4. 4运行 Python 对话示例

   把示例保存为 py 文件运行；先初始化 Manager，再从模型目录选取 qwen2.5-0.5b 下载并加载。

   from foundry_local_sdk import Configuration, FoundryLocalManager
   
   config = Configuration(app_name="foundry_local_samples")
   FoundryLocalManager.initialize(config)
   manager = FoundryLocalManager.instance
   
   # Select and load a model from the catalog
   model = manager.catalog.get_model("qwen2.5-0.5b")
   model.download()
   model.load()
   
   # Get a chat client
   client = model.get_chat_client()
   
   # Create and send message
   messages = [
       {"role": "user", "content": "What is the golden ratio?"}
   ]
   response = client.complete_chat(messages)
   print(f"Response: {response.choices[0].message.content}")
   
   model.unload()

   复制

5. 5获取完整安装包

   如需完整的本地运行时或非 npm/pip 的安装方式，可从官方下载页获取安装程序，文档见官方文档站。

关键配置

如何确认成功

示例程序控制台打印出模型对 “What is the golden ratio?” 的回答内容，即表示本地推理链路已跑通。

常见问题

注意事项

• 运行时体积很小（约 20 MB），便于随应用分发给最终用户。
• 模型首次使用需要下载，示例中用进度回调打印下载百分比。
• 示例代码用完后调用 unload() 释放模型，避免长期占用本地内存与显存。
• 本项目面向硬件受限的单用户设备优化，不适合作为高并发服务端推理栈。