本地部署.LLM

一个注重隐私的文档智能工具包——默认本地运行，同时支持云端

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

主要特性：

• 完全本地执行，并可根据需要选择使用云端服务。详情请参阅速查表。
• 针对多种任务的分析流水线，包括信息抽取、摘要生成、分类、问答以及智能代理等。
• 通过诸如SparseStore等模块，支持计算资源有限的环境（例如，无需预先存储嵌入即可实现RAG）。
• 可轻松与本地环境中的现有工具集成，如Elasticsearch和SharePoint。
• 提供一个可视化工作流构建器，可通过点选式界面组装复杂的文档分析流水线。

完整文档请见这里。

快速入门

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

# 使用Ollama作为后端的本地LLM
!ollama pull llama3.2
llm = LLM('ollama/llama3.2')

# 基本提示
result = llm.prompt('给我一个关于LLM的简短一句话定义。')

# RAG
utils.download('https://www.arxiv.org/pdf/2505.07672', '/tmp/my_documents/paper.pdf')
llm.ingest('/tmp/my_documents')
result = llm.ask('OnPrem.LLM是什么？')

# 切换到以Anthropic为后端的云端LLM
llm = LLM("anthropic/claude-3-7-sonnet-latest")

# 结构化输出
from pydantic import BaseModel, Field
class MeasuredQuantity(BaseModel):
    value: str = Field(description="数值")
    unit: str = Field(description="计量单位")
structured_output = llm.pydantic_prompt('他当时的速度是35英里每小时。', pydantic_model=MeasuredQuantity)
print(structured_output.value) # 35
print(structured_output.unit)  # 英里/小时

# 安全启动沙盒化的AI智能代理
from onprem.pipelines import AgentExecutor
executor = AgentExecutor(model='openai/gpt-5-mini', sandbox=True)
result = executor.run("""
搜索此目录下的所有.md文件，并：
1. 提取所有标题（# ## ###）
2. 统计每个文件的总字数
3. 创建一个索引文件'documentation_index.md'，内容包括：
   - 所有Markdown文件的列表
   - 每个文件的字数统计
   - 主要讨论的主题（从标题中提取）
""")

支持的LLM后端众多，例如： llama_cpp、 transformers、 Ollama、 vLLM、 OpenAI、 Anthropic 等。

---

安装 | 使用方法 | Web UI | 示例 | 常见问题 | 如何引用

最新消息 🔥

• [2026年3月] 发布v0.22.0版本，新增AgentExecutor：只需两行代码即可在沙盒环境中安全启动AI智能代理来解决问题。详情请参阅关于智能代理的示例笔记本。
• [2026年1月] 发布v0.21.0版本，新增支持基于元数据的查询路由。详情请参阅此处的查询路由示例。此外，本次发布还包括提供商原生支持的结构化输出（例如，OpenAI、Anthropic和AWS GovCloud Bedrock提供的结构化输出）。
• [2025年12月] 发布v0.20.0版本，新增支持异步提示。详情请参阅此处的示例。
• [2025年9月] 发布v0.19.0版本，新增支持工作流：用于复杂文档分析的YAML配置流水线。更多信息请参阅工作流文档。
• [2025年8月] 发布v0.18.0版本，现已可与AWS GovCloud的LLM一起使用。更多信息请参阅此处的示例。
• [2025年7月] 发布v0.17.0版本，现在可以直接连接到SharePoint进行搜索和RAG操作。更多信息请参阅关于向量存储的示例笔记本。

---

安装

在您已经安装 PyTorch 之后，您可以使用以下命令安装 OnPrem.LLM：

pip install onprem

Chroma：如果您使用默认的 Chroma “Dense” 向量存储（而不是 稀疏向量存储）进行 RAG 操作，请运行 pip install[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 后端。
• 您通过提供 model_id 参数来实例化 LLM，从而使用 Hugging Face Transformers（而非 llama-cpp-python）作为 LLM 后端，如此处所示。
• 您正在使用 OnPrem.LLM 并通过 外部 REST API 提供的 LLM（例如 vLLM、OpenLLM）。
• 您正在使用 OnPrem.LLM 与 云端 LLM 配合使用（请参阅下方的备忘单）。

使用 llama-cpp-python 进行 GPU 加速推理

当您使用 pip install llama-cpp-python 安装 llama-cpp-python 时，LLM 将在您的 CPU 上运行。为了更快地生成答案，您可以根据您的操作系统构建 llama-cpp-python，使其在您的 GPU 上运行。

• 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, ...)

通常，参数量为 80 亿及以下的量化模型可以在显存仅为 6GB 的 GPU 上运行。如果模型无法完全加载到您的 GPU 中（例如出现“CUDA Error: Out-of-Memory”错误），您可以尝试调整 n_gpu_layers 参数的值（例如 n_gpu_layers=20），将部分层卸载到 CPU 上。如上所示设置 n_gpu_layers=-1 则会将所有层卸载到 GPU 上。

如果您在安装 llama-cpp-python 时遇到问题，可以参阅常见问题解答获取更多提示。

使用方法

设置

from onprem import LLM

llm = LLM(verbose=False) # 默认使用默认模型和后端

备忘单

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

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

• 通过 URL 使用选定的 GGUF 模型：

   # 对于用户提供的 GGUF 模型，需要提示模板（详见 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)
  

• 通过文件路径使用选定的 GGUF 模型：

   # 对于用户提供的 GGUF 模型，需要提示模板（详见 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 参数）。

• 使用 gpt-oss 的 vLLM（假设已向 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" # 根据需要替换
  # 设置 LLM 与 AWS GovCloud 上的 Bedrock 的连接
  llm = LLM( f"govcloud-bedrock://{inference_arn}", region_name=region_name, endpoint_url=endpoint_url)
  response = llm.prompt("写一首关于月亮的俳句。")
  

以上实例将在下文中更详细地介绍。

GGUF 模型与 Llama.cpp

默认的 LLM 后端是 llama-cpp-python，而默认模型目前是一个名为 Zephyr-7B-beta 的 70 亿参数模型，该模型会自动下载并使用。Llama.cpp 运行的模型采用 GGUF 格式。另外两个默认模型是 llama 和 mistral。例如，如果提供了 default_model='llama'，那么系统会自动下载并使用一个 Llama-3.1-8B-Instsruct 模型：

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

选择您自己的模型： 当然，您也可以轻松地为 LLM 提供您所选 LLM 的 URL 或路径（有关示例，请参阅 常见问题解答）。

提供额外参数： 任何传递给 LLM 的额外参数都会直接转发给默认的 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
lm = 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 的更多信息，请参阅 此处。

关于如何在 OnPrem.LLM 中专门使用 OpenAI 模型的更多信息，请参阅 此处。

向 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 参数控制。

使用 Hugging Face Transformers 替代 Llama.cpp

默认情况下，OnPrem.LLM 使用的 LLM 后端是 llama-cpp-python，该后端要求模型采用 GGUF 格式。从版本 0.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 模块上以 SafeTensors 格式 存储的任何模型，只要这些模型能够通过 Hugging Face 的 transformers.pipeline 加载即可。需要注意的是，当使用 model_id 参数时，prompt_template 会由 transformers 自动设置。

上述加载的 Llama-3.1 模型是使用 AWQ 量化的，这使得该模型能够在较小的 GPU 上运行（例如配备 6GB 显存的笔记本电脑 GPU），类似于默认的 GGUF 格式。使用 AWQ 量化的模型需要安装 autoawq 包：pip install autoawq（AWQ 仅支持 Linux 系统，包括 Windows Subsystem for Linux）。如果您需要加载未量化的模型，可以在加载时指定量化配置（称为“飞行中量化”）。在下面的示例中，我们加载了一个未量化的 Zephyr-7B-beta 模型，它将在加载过程中被量化，以便能够在显存仅为 6GB 的 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 库——这是一个轻量级的 Python 封装库，用于 CUDA 自定义函数，特别是 8 位优化器、矩阵乘法（LLM.int8()）以及 8 和 4 位量化功能。目前，bitsandbytes 团队正在努力支持除 CUDA 之外的其他后端。如果您遇到与 bitsandbytes 相关的错误，请参考 bitsandbytes 文档。

内置 Web 应用

OnPrem.LLM 包含一个内置的 Web 应用，用于访问 LLM。安装完成后，运行以下命令即可启动：

onprem --port 8000

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

更多信息，请参阅相关文档。

示例

文档中包含大量示例。

💡 入门

文档链接	示例
提示示例	使用提示解决问题

📚 文档处理

文档链接	示例
文本提取	文档文本提取（PDF、Word、PowerPoint）
文档摘要	文档摘要
信息抽取	从文档中抽取信息

🧠 问答与搜索

文档链接	示例
RAG 示例	基于 RAG 的问答
向量存储教程	使用不同的向量存储
语义相似度	计算文本之间的语义相似度

🎯 分类与分析

文档链接	示例
文本分类	少样本文本分类
问卷分析	定性问卷回复的自动编码
法律分析	法律及监管文件分析

🛠️ 高级功能

文档链接	示例
代理示例	基于代理的任务执行与工具
结构化输出	使用 Pydantic 模型实现结构化和引导式输出
工作流构建器	用于文档分析的工作流构建器

常见问题解答

1. 如何将其他模型与 OnPrem.LLM 一起使用？

   您可以使用 model_url 和 model_id 参数为 LLM 提供任意自定义模型（请参阅上方的速查表）。

   下面我们将详细介绍如何使用 llma.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 配置中指定）。

   # 如何在 OnPrem.LLM 中使用 Zephyr-7B
   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("列出三个可爱的猫名字。")
   

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

2. 在 Windows/Mac/Linux 上安装 onprem 时，我遇到了与 llama-cpp-python（或 chroma-hnswlib）相关的“构建”错误，这是为什么？

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

   对于 Ubuntu 等 Linux 系统，您可以尝试运行：sudo apt-get install build-essential g++ clang。更多技巧请参见 此处。

对于 Windows 系统，请尝试按照 这些说明 操作。 我们建议您使用 适用于 Linux 的 Windows 子系统 (WSL)，而不是直接使用 Microsoft Windows。如果您确实需要直接使用 Microsoft Windows，请务必安装 Microsoft C++ 构建工具，并确保选中 使用 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 版本）。

3. 我位于企业防火墙之后，在尝试下载模型时收到 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
   

4. 如何在没有互联网连接的机器上使用它？

   使用 LLM.download_model 方法将模型文件下载到 <your_home_directory>/onprem_data，然后将其传输到气隙机器上的相同位置。

   对于 ingest 和 ask 方法，您还需要下载并传输嵌入模型文件：

   from sentence_transformers import SentenceTransformer
   model = SentenceTransformer('sentence-transformers/all-MiniLM-L6-v2')
   model.save('/some/folder')
   

   将 some/folder 文件夹复制到气隙机器上，并通过 embedding_model_name 参数将路径提供给 LLM。

5. 当我调用 llm = LLM(...) 时，模型无法加载吗？

   这可能是由于模型文件损坏所致（此时应从 <home directory>/onprem_data 中删除并重新下载）。也可能是 llama-cpp-python 的版本需要升级到最新版。

6. 我在实例化 langchain.llms.Llamacpp 或 onprem.LLM 对象时遇到 “非法指令（核心已转储）” 错误吗？

   您的 CPU 可能不支持 cmake 由于某种原因所使用的指令（例如，由于 VirtualBox 设置中的 Hyper-V 导致)。您可以在构建和安装 llama-cpp-python 时尝试禁用这些指令：

   # 示例
   CMAKE_ARGS="-DGGML_CUDA=ON -DGGML_AVX2=OFF -DGGML_AVX=OFF -DGGML_F16C=OFF -DGGML_FMA=OFF" FORCE_CMAKE=1 pip install --force-reinstall llama-cpp-python --no-cache-dir
   

7. 如何加快 LLM.ingest 的速度？

   默认情况下，如果有可用的 GPU，将会用于计算嵌入向量，因此请确保 PyTorch 已安装并支持 GPU。您可以通过 embedding_model_kwargs 参数显式控制用于计算嵌入向量的设备。

   from onprem import LLM
   llm  = LLM(embedding_model_kwargs={'device':'cuda'})
   

   您还可以向 LLM 提供 store_type="sparse" 参数，以使用稀疏向量存储，这会牺牲少量推理速度（LLM.ask），但在摄入阶段（LLM.ingest）可显著提升速度。

   from onprem import LLM
   llm  = LLM(store_type="sparse")
   

   请注意，与密集向量存储不同，稀疏向量存储假设答案来源至少包含与问题共有的一个词。

引用方式

在使用 OnPrem.LLM 时，请引用 以下论文：

@article{maiya2025generativeaiffrdcs,
      title={FFRDCs 的生成式 AI}, 
      author={Arun S. Maiya},
      year={2025},
      eprint={2509.21040},
      archivePrefix={arXiv},
      primaryClass={cs.CL},
      url={https://arxiv.org/abs/2509.21040}, 
}

OnPrem.LLM 快速上手指南

OnPrem.LLM 是一个注重隐私的 Python 工具包，专为在离线或受限环境中对敏感数据应用大语言模型（LLM）而设计。它默认支持完全本地化运行，同时也兼容 OpenAI、Anthropic 等云端模型提供商。

1. 环境准备

系统要求

• 操作系统：Linux, macOS, Windows (WSL2 推荐用于 GPU 加速)
• Python：3.8+
• 硬件：
  • CPU 模式：无特殊要求，适合资源有限的环境。
  • GPU 模式：推荐使用 NVIDIA 显卡（6GB+ VRAM 可运行 8B 参数量化模型）。需安装最新的 NVIDIA 驱动和 CUDA Toolkit。

前置依赖

在使用 GPU 加速的 llama-cpp-python 后端前，请确保已安装 PyTorch（可选，视具体后端而定）及对应的编译环境。

国内开发者提示：建议使用国内镜像源加速 Python 包下载，例如清华源或阿里源。

2. 安装步骤

基础安装

使用 pip 安装核心库：

pip install onprem -i https://pypi.tuna.tsinghua.edu.cn/simple

可选组件安装

根据您的需求选择安装以下扩展：

• 启用 Chroma 向量数据库（用于 RAG 检索增强生成）：

  pip install "onprem[chroma]" -i https://pypi.tuna.tsinghua.edu.cn/simple
  

• 启用 AI Agent 功能（沙箱执行）：

  pip install "onprem[agent]" -i https://pypi.tuna.tsinghua.edu.cn/simple
  

GPU 加速配置（可选）

若需使用 GPU 加速本地模型推理（基于 llama-cpp-python），请根据操作系统执行以下命令重新构建该库：

• Linux:

  CMAKE_ARGS="-DGGML_CUDA=on" FORCE_CMAKE=1 pip install --upgrade --force-reinstall llama-cpp-python --no-cache-dir -i https://pypi.tuna.tsinghua.edu.cn/simple
  

• macOS (Apple Silicon):

  CMAKE_ARGS="-DGGML_METAL=on" pip install llama-cpp-python -i https://pypi.tuna.tsinghua.edu.cn/simple
  

• Windows: 建议参考官方文档在 WSL2 中配置，或使用预编译 wheel。

3. 基本使用

初始化与本地模型运行

以下示例展示如何使用 Ollama 作为后端运行本地模型（需先安装并运行 Ollama 服务）。

# 安装依赖
# !pip install onprem[chroma]

from onprem import LLM, utils

# 拉取本地模型 (需在终端先运行: ollama pull llama3.2)
# !ollama pull llama3.2

# 初始化本地 LLM (使用 Ollama 后端)
llm = LLM('ollama/llama3.2')

# 基础对话
result = llm.prompt('Give me a short one sentence definition of an LLM.')
print(result)

文档问答 (RAG)

将本地文档导入并进行问答，无需预先计算嵌入向量（支持 SparseStore）。

# 下载示例文档
utils.download('https://www.arxiv.org/pdf/2505.07672', '/tmp/my_documents/paper.pdf')

#  ingest 文档到本地向量库
llm.ingest('/tmp/my_documents')

# 针对文档内容提问
result = llm.ask('What is OnPrem.LLM?')
print(result)

切换至云端模型

轻松切换至云端大模型（如 Anthropic 或 OpenAI），需配置对应 API Key。

# 切换到 Anthropic Claude 模型
# 请确保环境变量中设置了 ANTHROPIC_API_KEY
llm = LLM("anthropic/claude-3-7-sonnet-latest")

result = llm.prompt('Summarize the benefits of local LLMs.')
print(result)

结构化输出

利用 Pydantic 模型获取标准化的 JSON 输出。

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(f"Value: {structured_output.value}") # 输出: 35
print(f"Unit: {structured_output.unit}")   # 输出: mph

安全运行 AI Agent

在沙箱环境中启动 AI Agent 执行文件操作任务。

from onprem.pipelines import AgentExecutor

# 初始化 Agent (以 OpenAI 为例，需设置 OPENAI_API_KEY)
executor = AgentExecutor(model='openai/gpt-4o-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 the results.
""")