第三节：在FoundryLocal中使用开源模型

第三节：在 Foundry Local 中使用开源模型

摘要

了解如何将 Hugging Face 和其他开源模型引入 Foundry Local。学习模型选择策略、社区贡献工作流程、性能比较方法，以及如何通过自定义模型注册扩展 Foundry。本节内容与每周的“模型星期一”探索主题相关，帮助您在扩展到 Azure 之前，在本地评估和运营开源模型。

学习目标

完成本节后，您将能够：

• 发现与评估：通过质量与资源权衡，识别候选模型（mistral、gemma、qwen、deepseek）。
• 加载与运行：使用 Foundry Local CLI 下载、缓存并启动社区模型。
• 基准测试：应用一致的延迟 + 令牌吞吐量 + 质量评估方法。
• 扩展：按照与 SDK 兼容的模式注册或调整自定义模型包装器。
• 比较：为 SLM 与中型 LLM 的选择决策生成结构化比较。

前置条件

• 已完成第一节和第二节
• 安装了 foundry-local-sdk 的 Python 环境
• 至少有 15GB 的磁盘空间用于多个模型缓存

跨平台环境快速启动

Windows PowerShell:

py -m venv .venv
 .\.venv\Scripts\Activate.ps1
pip install --upgrade pip
pip install foundry-local-sdk openai numpy
​

macOS / Linux:

python3 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
pip install foundry-local-sdk openai numpy
​

在 macOS 上对 Windows 主机服务进行基准测试时，设置：

export FOUNDRY_LOCAL_ENDPOINT=http://<windows-host>:5273/v1
​

演示流程（30分钟）

1. 通过 CLI 加载 Hugging Face 模型（8分钟）

# List catalog entries (filter manually if needed)
foundry model list

# Download a set of comparison targets
foundry model download mistral-7b
foundry model download gemma-2-2b
foundry model download qwen2.5-0.5b

# Verify cache
foundry cache list
​

2. 运行与快速探测（5分钟）

foundry model run qwen2.5-0.5b
foundry model run qwen2.5-0.5b --prompt "List three benefits of local inference."

foundry model run mistral-7b
foundry model run mistral-7b --prompt "Explain retrieval augmented generation in one paragraph."
​

3. 基准测试脚本（8分钟）

创建 samples/03-oss-models/benchmark_models.py：

#!/usr/bin/env python3
"""Lightweight benchmarking for open-source models in Foundry Local.
Metrics: first token latency, total latency, tokens/sec (approx via usage), model size indicator.
Reference SDK: https://github.com/microsoft/Foundry-Local/tree/main/sdk/python
"""

import time, statistics, json
from openai import OpenAI

MODELS = [
    "qwen2.5-0.5b",
    "gemma-2-2b",
    "mistral-7b",
]

PROMPT = "Explain the principle of retrieval augmented generation in 2 sentences."
ROUNDS = 3

client = OpenAI(base_url="http://localhost:5273/v1", api_key="not-needed")

def run_round(model: str):
    start = time.time()
    resp = client.chat.completions.create(
        model=model,
        messages=[{"role": "user", "content": PROMPT}],
        max_tokens=150,
        temperature=0.2,
        stream=False
    )
    end = time.time()
    usage = getattr(resp, "usage", None)
    total_tokens = usage.total_tokens if usage else None
    return {
        "latency_sec": end - start,
        "total_tokens": total_tokens,
        "tokens_per_sec": (total_tokens / (end - start)) if (total_tokens and (end-start) > 0) else None,
        "sample_response": resp.choices[0].message.content[:160].replace("\n", " ")
    }

def benchmark_model(model: str):
    results = [run_round(model) for _ in range(ROUNDS)]
    latencies = [r["latency_sec"] for r in results]
    tps = [r["tokens_per_sec"] for r in results if r["tokens_per_sec"]]
    return {
        "model": model,
        "rounds": ROUNDS,
        "latency_avg": statistics.mean(latencies),
        "latency_p95": statistics.quantiles(latencies, n=20)[-1] if len(latencies) > 1 else latencies[0],
        "tokens_per_sec_avg": statistics.mean(tps) if tps else None,
        "sample": results[-1]["sample_response"]
    }

def main():
    summary = [benchmark_model(m) for m in MODELS]
    print(json.dumps(summary, indent=2))
    print("\nInterpretation Tips:\n- latency_avg: lower better\n- tokens_per_sec_avg: higher better\n- Compare quality manually on sample outputs.")

if __name__ == "__main__":
    main()
​

运行：

python samples/03-oss-models/benchmark_models.py
​

4. 比较性能（5分钟）

讨论权衡：加载时间、内存占用（观察任务管理器 / nvidia-smi / 操作系统资源监视器）、输出质量与速度。使用 Python 基准测试脚本（第三节）进行延迟和吞吐量测试；启用 GPU 加速后重复测试。

5. 初始项目（4分钟）

创建一个模型比较报告生成器（扩展基准测试脚本，支持导出为 Markdown）。

初始项目：扩展 03-huggingface-models

通过以下方式增强现有示例：

1. 添加基准测试聚合 + CSV/Markdown 输出。
2. 实现简单的定性评分（提示对 + 手动注释存根文件）。
3. 引入 JSON 配置文件（models.json），支持可插拔的模型列表和提示集。

验证清单

foundry cache list
foundry model run qwen2.5-0.5b
curl http://localhost:5273/v1/models
​

所有目标模型应出现并响应探测聊天请求。

示例场景与工作坊映射

场景叙述

产品工程团队需要为离线会议记录功能选择一个默认的轻量级摘要模型。他们在固定的提示集上运行受控的确定性基准测试（temperature=0），并收集启用和未启用 GPU 加速时的延迟和吞吐量指标。

示例提示集 JSON（可扩展）

[
    "Explain the principle of retrieval augmented generation in 2 sentences.",
    "List 3 privacy benefits of local inference.",
    "Summarize why model size impacts latency on consumer hardware.",
    "Provide two scenarios where an SLM is preferable to an LLM."
]
​

对每个模型循环每个提示，捕获每个提示的延迟以推导分布指标并检测异常值。

模型选择框架

使用自定义模型扩展

高级模式（伪代码）：

# pseudo_adapter.py (conceptual)
class CustomModelAdapter:
    def load(self, weights_path: str): ...
    def generate(self, prompt: str, **params) -> str: ...

# Register with local routing (future extensibility point)
​

请参考官方仓库以获取不断更新的适配器接口：
https://github.com/microsoft/Foundry-Local/tree/main/sdk/python

故障排除

参考资料

• Foundry Local SDK: https://github.com/microsoft/Foundry-Local/tree/main/sdk/python
• 模型星期一: https://aka.ms/model-mondays
• Hugging Face 模型发现: https://huggingface.co/models

课程时长：30分钟（+ 可选深入探讨）
难度：中级

可选增强功能

最小 Markdown 导出片段

with open("benchmark_report.md", "w") as f:
        f.write("|Model|Avg Latency|p95|TPS|\n|---|---|---|---|\n")
        for row in summary:
                f.write(f"|{row['alias']}|{row['latency_avg']:.2f}|{row['latency_p95']:.2f}|{(row.get('tokens_per_sec_avg') or 0):.1f}|\n")
​

确定性提示集示例

[
    "Summarize retrieval augmented generation.",
    "List 3 privacy benefits of local inference.",
    "Explain when to choose an SLM over an LLM."
]
​

循环静态列表而非随机提示，以便在不同提交间进行可比的指标测试。

免责声明：
本文档使用AI翻译服务Co-op Translator进行翻译。尽管我们努力确保翻译的准确性，但请注意，自动翻译可能包含错误或不准确之处。原始语言的文档应被视为权威来源。对于重要信息，建议使用专业人工翻译。我们对因使用此翻译而产生的任何误解或误读不承担责任。