三行代码快速搭建本地LLM应用

OnPrem.LLM

隐私友好的文档智能工具包——默认本地运行，支持云端

OnPrem.LLM（简称"OnPrem"）是一个基于 Python 的工具包，用于在离线或受限环境中将大语言模型（LLMs）应用于敏感的非公开数据。该项目在很大程度上受到 privateGPT 项目的启发，OnPrem.LLM 设计用于完全本地执行，但也支持与广泛的云端 LLM 提供商（如 OpenAI、Anthropic）集成。

完全本地执行，必要时可利用云端。参见速查表。

支持多种不同任务的分析管道，包括信息提取、摘要生成、分类、问答和 AI 智能体。

通过 SparseStore 等模块为计算资源有限的环境提供支持（例如，无需提前存储嵌入向量的 RAG）。

易于与本地环境中的现有工具集成，如 Elasticsearch 和 Sharepoint。

可视化工作流构建器，通过点击界面组装复杂的文档分析管道。

完整文档在此。

# install
!pip install onprem[chroma]
from onprem import LLM, utils

# local LLM with Ollama as backend
!ollama pull llama3.2
llm = LLM('ollama/llama3.2')

# basic prompting
result = llm.prompt('Give me a short one sentence definition of an LLM.')

# RAG
utils.download('https://www.arxiv.org/pdf/2505.07672', '/tmp/my_documents/paper.pdf')
llm.ingest('/tmp/my_documents')
result = llm.ask('What is OnPrem.LLM?')

# switch to cloud LLM using Anthropic as backend
llm = LLM("anthropic/claude-sonnet-4-5-20250929")

# structured outputs
from pydantic import BaseModel, Field
class MeasuredQuantity(BaseModel):
    value: str = Field(description="numerical value")
    unit: str = Field(description="unit of measurement")
structured_output = llm.pydantic_prompt('He was going 35 mph.', pydantic_model=MeasuredQuantity)
print(structured_output.value) # 35
print(structured_output.unit)  # mph

# Safely launch a sandboxed AI agent
from onprem.pipelines import AgentExecutor
executor = AgentExecutor(model='openai/gpt-5-mini', sandbox=True)
result = executor.run("""
Search this directory for all .md files and:
1. Extract all headings (# ## ###)
2. Count total words in each file
3. Create an index file 'documentation_index.md' with:
   - List of all markdown files
   - Word count for each
   - Main topics covered (from headings)
""")

支持许多 LLM 后端（例如 llama_cpp、transformers、Ollama、vLLM、OpenAI、Anthropic 等）。

安装 | 使用 | Web UI | 示例 | FAQ | 如何引用

[2026/06] 发布 v0.23.0，包含改进的信息提取功能。

[2026/03] 发布 v0.22.0，现已包含 AgentExecutor：在沙箱环境中安全启动 AI 智能体，用两行代码解决问题。参见代理示例笔记本。

[2026/01] 发布 v0.21.0，现已支持基于元数据的查询路由。参见查询路由示例。本版本还包括：提供商实现的结构化输出（如 OpenAI、Anthropic 和 AWS GovCloud Bedrock 的结构化输出）。

[2025/12] 发布 v0.20.0，现已支持异步提示。参见示例。

[2025/09] 发布 v0.19.0，现已支持工作流：用于复杂文档分析的 YAML 配置管道。详见工作流文档。

[2025/08] 发布 v0.18.0，现可与 AWS GovCloud LLMs 配合使用。详见此示例。

安装 PyTorch 后，可以用以下命令安装 OnPrem.LLM：

pip install onprem

Chroma：如果使用 RAG 且采用默认的 Chroma "Dense" 向量存储（而非稀疏向量存储），运行 pip install onprem[chroma]。

AI 智能体：如果使用 OnPrem.LLM 启动 AI 智能体，运行 pip install onprem[agent]。

Llama-cpp-python 是可选的：

如果使用 llama-cpp-python 作为 LLM 后端：

CPU：pip install llama-cpp-python（Microsoft Windows 需额外步骤）

GPU：按下面的说明操作。

在以下任何情况为真时，安装 llama-cpp-python 是可选的：

你使用 Ollama 作为 LLM 后端。

你使用 Hugging Face Transformers（而非 llama-cpp-python）作为 LLM 后端，通过在实例化 LLM 时提供 model_id 参数，如此处所示。

你使用 OnPrem.LLM 搭配通过外部 REST API 提供的 LLM（如 vLLM、OpenLLM）。

你使用 OnPrem.LLM 搭配云端 LLM（参见下面的速查表）。

GPU 加速推理与 llama-cpp-python

使用 pip install llama-cpp-python 安装 llama-cpp-python 时，LLM 将在 CPU 上运行。为了显著加快答案生成速度，你可以通过根据你的操作系统编译 llama-cpp-python 来在 GPU 上运行 LLM。

Linux：CMAKE_ARGS="-DGGML_CUDA=on" FORCE_CMAKE=1 pip install --upgrade --force-reinstall llama-cpp-python --no-cache-dir

Mac：CMAKE_ARGS="-DGGML_METAL=on" pip install llama-cpp-python

Windows 11：按此处的说明操作。

Windows Subsystem for Linux (WSL2)：按此处的说明操作。

对于 Linux 和 Windows，在运行上述安装命令前，你需要安装最新的 NVIDIA 驱动程序以及 CUDA 工具包。

按照上述说明操作后，在实例化 LLM 时提供 n_gpu_layers=-1 参数，以使用 GPU 进行快速推理：

llm = LLM(n_gpu_layers=-1, ...)

参数为 8B 及以下的量化模型通常可在仅 6GB VRAM 的 GPU 上运行。如果模型无法装入你的 GPU（例如，你收到 "CUDA Error: Out-of-Memory" 错误），可以通过对 n_gpu_layers 参数尝试不同的值（例如 n_gpu_layers=20）来将部分层卸载到 GPU。如上所示设置 n_gpu_layers=-1 将所有层都卸载到 GPU。

如果遇到 llama-cpp-python 安装问题，参见 FAQ 获得额外提示。

from onprem import LLM

llm = LLM(verbose=False) # default model and backend are used

本地模型：支持许多不同的本地 LLM 后端。

Llama-cpp：llm = LLM(default_model="llama", n_gpu_layers=-1)

Llama-cpp：llm = LLM(default_model="llama", n_gpu_layers=-1)

Llama-cpp 搭配通过 URL 选择的 GGUF 模型：

# prompt templates are required for user-supplied GGUF models (see FAQ)
llm = LLM(model_url='https://huggingface.co/TheBloke/zephyr-7B-beta-GGUF/resolve/main/zephyr-7b-beta.Q4_K_M.gguf', prompt_template= "<|system|>\n</s>\n<|user|>\n{prompt}</s>\n<|assistant|>", n_gpu_layers=-1)

Llama-cpp 搭配通过文件路径选择的 GGUF 模型：

# prompt templates are required for user-supplied GGUF models (see FAQ)
llm = LLM(model_url='zephyr-7b-beta.Q4_K_M.gguf', 
          model_download_path='/path/to/folder/to/where/you/downloaded/model',
          prompt_template= "<|system|>\n</s>\n<|user|>\n{prompt}</s>\n<|assistant|>", n_gpu_layers=-1)

Hugging Face Transformers：llm = LLM(model_id='Qwen/Qwen2.5-0.5B-Instruct', device='cuda')

Ollama：llm = LLM(model_url="ollama://llama3.2", api_key='na')

也支持 Ollama：llm = LLM(model_url="ollama/llama3.2", api_key='na')

也支持 Ollama：llm = LLM(model_url='http://localhost:11434/v1', api_key='na', model='llama3.2')

vLLM：llm = LLM(model_url='http://localhost:8666/v1', api_key='na', model='Qwen/Qwen2.5-0.5B-Instruct')

也支持 vLLM：llm = LLM('hosted_vllm/served-model-name', api_base="http://localhost:8666/v1", api_key="test123")（假设向 vllm.entrypoints.openai.api_server 提供了 served-model-name 参数）。

vLLM with gpt-oss

vLLM with gpt-oss（假设向 vLLM 供应了 served-model-name 参数）：

# 重要：由于生成的中间推理步骤，需要将 max_tokens 设置为较高的值
llm = LLM(model_url='http://localhost:8666/v1', api_key='your_api_key', model=served_model_name, max_tokens=32000)
result = llm.prompt(prompt, reasoning_effort="high")

云模型

除了本地 LLM 外，LiteLLM 支持的所有云 LLM 提供商都兼容：

Anthropic Claude：

llm = LLM(model_url="anthropic/claude-3-7-sonnet-latest")

OpenAI GPT-4o：

llm = LLM(model_url="openai/gpt-4o")

AWS GovCloud Bedrock（假设 AWS_ACCESS_KEY_ID 和 AWS_SECRET_ACCESS_KEY 已设置为环境变量）：

from onprem import LLM
inference_arn = "YOUR INFERENCE ARN"
endpoint_url = "YOUR ENDPOINT URL"
region_name = "us-gov-east-1" # 根据需要替换
# 设置与 AWS GovCloud 上 Bedrock 的 LLM 连接
llm = LLM(f"govcloud-bedrock://{inference_arn}", region_name=region_name, endpoint_url=endpoint_url)
response = llm.prompt("Write a haiku about the moon.")

上述实例化方式的详细描述见下文。

默认的 LLM 后端是 llama-cpp-python，默认模型当前是一个 7B 参数的模型，称为 Zephyr-7B-beta，它会被自动下载和使用。Llama.cpp 以 GGUF 格式运行模型。另外两个默认模型是 llama 和 mistral。例如，如果提供 default_model='llama'，则会自动下载并使用 Llama-3.1-8B-Instruct 模型：

# Llama 3.1 在此下载，Llama-3.1 的正确提示模板会自动配置并使用
llm = LLM(default_model='llama')

选择自己的模型

当然，你也可以轻松地向 LLM 提供你选择的 LLM 的 URL 或路径（详见常见问题的示例）。

提供额外参数

提供给 LLM 的任何额外参数都会直接转发给 llama-cpp-python（默认的 LLM 后端）。

如果向 LLM 提供 default_engine="transformers"，则使用 Hugging Face transformers 作为 LLM 后端。LLM 的额外参数（例如 device='cuda'）会直接转发给 transformers.pipeline。如果提供 model_id 参数，默认 LLM 后端会自动更改为 Hugging Face transformers。

# 使用 AWQ 量化的 Llama-3.1 模型通过 Hugging Face transformers 下载并运行（需要 GPU）
llm = LLM(default_model='llama', default_engine='transformers')

# 使用 Hugging Face Transformers 的自定义模型
llm = LLM(model_id='Qwen/Qwen2.5-0.5B-Instruct', device_map='cpu')

更多关于使用 Hugging Face transformers 作为 LLM 后端的信息，详见这里。

你也可以连接到 Ollama、本地 LLM API（例如 vLLM）和云 LLM。

# 连接到由 Ollama 提供的 LLM
llm = LLM(model_url='ollama/llama3.2')

# 连接到通过 vLLM 提供的 LLM（根据需要设置 API 密钥）
llm = LLM(model_url='http://localhost:8000/v1', api_key='token-abc123', model='Qwen/Qwen2.5-0.5B-Instruct')

# 连接到云支持的 LLM（例如 OpenAI、Anthropic）
llm = LLM(model_url="openai/gpt-4o-mini")  # OpenAI
llm = LLM(model_url="anthropic/claude-3-7-sonnet-20250219") # Anthropic

OnPrem.LLM 支持 LiteLLM 包支持的任何提供商和模型。

更多关于本地 LLM API 的信息详见这里。

更多关于专门使用 OpenAI 模型与 OnPrem.LLM 的信息详见这里。

提供给 LLM 和 LLM.prompt 的额外参数会直接传递给 LLM 后端。参数名称会根据你选择的后端而不同。

例如，对于默认的 llama-cpp 后端，默认上下文窗口大小（n_ctx）设置为 3900，默认输出大小（max_tokens）设置为 512。两者都是 LLM 的可配置参数。如果你有更大的提示或需要更长的输出，可以增加这些值。其他参数（例如 api_key、device_map 等）可以直接提供给 LLM，并会被路由到 LLM 后端或 API（例如 llama-cpp-python、Hugging Face transformers、vLLM、OpenAI 等）。max_tokens 参数也可以通过将其提供给 LLM.prompt 来即时调整。

另一方面，对于 Ollama 模型，上下文窗口和输出大小分别由 num_ctx 和 num_predict 控制。

使用 Hugging Face transformers 时，不需要设置上下文窗口大小，但输出大小由 LLM.prompt 的 max_new_tokens 参数控制。

默认情况下，OnPrem.LLM 使用的 LLM 后端是 llama-cpp-python，它需要 GGUF 格式的模型。从 v0.5.0 开始，现在可以使用 Hugging Face transformers 作为 LLM 后端。这通过使用 model_id 参数（而不是提供 model_url 参数）来实现。在下面的示例中，我们运行 Llama-3.1-8B 模型。

# 使用 model_id 参数时，不需要安装 llama-cpp-python
llm = LLM(model_id="hugging-quants/Meta-Llama-3.1-8B-Instruct-AWQ-INT4", device_map='cuda')

这使你能够更轻松地使用 Hugging Face hub 上任何以 SafeTensors 格式提供且可通过 Hugging Face transformers.pipeline 加载的模型。请注意，使用 model_id 参数时，prompt_template 会由 transformers 自动设置。

上面加载的 Llama-3.1 模型使用 AWQ 进行了量化，这允许模型适配更小的 GPU（例如具有 6GB VRAM 的笔记本电脑 GPU），类似于默认的 GGUF 格式。AWQ 模型需要安装 autoawq 包：pip install autoawq（AWQ 仅支持 Linux 系统，包括 Windows Subsystem for Linux）。如果你确实需要加载未量化的模型，可以在加载时提供量化配置（称为"在线量化"）。在下面的示例中，我们加载一个未量化的 Zephyr-7B-beta 模型，它将在加载期间进行量化，以适配仅有 6GB VRAM 的 GPU：

from transformers import BitsAndBytesConfig
quantization_config = BitsAndBytesConfig(
    load_in_4bit=True,
    bnb_4bit_quant_type="nf4",
    bnb_4bit_compute_dtype="float16",
    bnb_4bit_use_double_quant=True,
)
llm = LLM(model_id="HuggingFaceH4/zephyr-7b-beta", device_map='cuda', 
          model_kwargs={"quantization_config":quantization_config})

在提供 quantization_config 时，使用 bitsandbytes 库，这是围绕 CUDA 自定义函数的轻量级 Python 包装器，特别是 8 位优化器、矩阵乘法（LLM.int8()）和 8 位及 4 位量化函数。bitsandbytes 团队正在进行的努力是支持除 CUDA 外的多个后端。如果你收到与 bitsandbytes 相关的错误，请参考 bitsandbytes 文档。

OnPrem.LLM 包括一个内置的 Web 应用来访问 LLM。安装后，运行以下命令来启动它：

onprem --port 8000

然后，在 Web 浏览器中输入 localhost:8000（或如果在远程服务器上运行则输入 <domain_name>:8000）来访问应用：

更多信息见相应的文档。

文档包含许多示例。

📚 文档处理

🧠 问题回答与搜索

🎯 分类与分析

🛠️ 高级功能

如何在 OnPrem.LLM 中使用其他模型？

你可以使用 model_url 和 model_id 参数为 LLM 提供任何选择的模型（见上方备忘单）。

下面我们将详细介绍如何使用 llama.cpp 后端提供自定义 GGUF 模型。

你可以在 huggingface.co 上找到文件名中包含 GGUF 的 llama.cpp 支持的模型。

确保你指向的是实际 GGUF 模型文件的 URL，即模型页面上的"下载"链接。下面是 Mistral-7B 的示例：

使用 llama.cpp 后端时，GGUF 模型有需要提供给 LLM 的特定提示格式。例如，Zephyr-7B 所需的提示模板（如模型页面所述）为：

<|system|>\n</s>\n<|user|>\n{prompt}</s>\n<|assistant|>

因此，要使用 Zephyr-7B 模型，你必须为 LLM 构造函数提供 prompt_template 参数（或在 Web 应用的 webapp.yml 配置中指定它）。

# how to use Zephyr-7B with OnPrem.LLM
llm = LLM(model_url='https://huggingface.co/TheBloke/zephyr-7B-beta-GGUF/resolve/main/zephyr-7b-beta.Q4_K_M.gguf',
          prompt_template = "<|system|>\n</s>\n<|user|>\n{prompt}</s>\n<|assistant|>",
          n_gpu_layers=33)
llm.prompt("List three cute names for a cat.")

对于其他任何 LLM 后端，不需要提示模板（例如，使用 Ollama 作为后端或使用 transformers 模型的 model_id 参数时）。如果使用任何默认模型，也不需要提示模板。

安装 onprem 时，我在 Windows/Mac/Linux 上收到与 llama-cpp-python（或 chroma-hnswlib）相关的"构建"错误？

请参阅 LangChain 关于 llama.cpp 的文档，了解如何为你的系统安装 llama-cpp-python 包。不同操作系统的额外提示如下所示：

对于 Linux 系统（如 Ubuntu），尝试：sudo apt-get install build-essential g++ clang。其他提示见这里。

对于 Windows 系统，请按照这些说明操作。我们建议你使用 Windows Subsystem for Linux (WSL) 而不是直接使用 Microsoft Windows。如果你必须直接使用 Microsoft Windows，请确保安装了 Microsoft C++ Build Tools 并勾选了"Desktop development with C++"。

对于 Mac，尝试按照这些提示操作。

在 privateGPT 仓库的此线程中，每个上述操作系统都有其他各种提示。当然，你也可以轻松在 Google Colab 上使用 OnPrem.LLM。

最后，如果你仍然无法解决 llama-cpp-python 构建问题，可以尝试为你的系统安装预构建的 wheel 文件：

示例：pip install llama-cpp-python==0.2.90 --extra-index-url https://abetlen.github.io/llama-cpp-python/whl/cpu

提示：chroma-hnswlib 也有预构建的 wheel 文件。如果运行 pip install onprem 在构建 chroma-hnswlib 时失败，可能是因为你使用的 Python 版本还没有预构建的 wheel 文件（这种情况下你可以尝试降级 Python）。

我在公司防火墙后面，尝试下载模型时收到 SSL 错误？

from onprem import LLM
LLM.download_model(url, ssl_verify=False)

你可以如下下载嵌入模型（由 LLM.ingest 和 LLM.ask 使用）：

wget --no-check-certificate https://public.ukp.informatik.tu-darmstadt.de/reimers/sentence-transformers/v0.2/all-MiniLM-L6-v2.zip

将解压后的文件夹名作为 embedding_model_name 参数提供给 LLM。

如果在运行 pip install 时甚至也收到 SSL 错误，尝试：

pip install –-trusted-host pypi.org –-trusted-host files.pythonhosted.org pip_system_certs

如何在没有互联网访问的机器上使用此功能？

使用 LLM.download_model 方法来