local-llm-provider

Local LLM Provider 是一个用于连接本地大语言模型端点的技能，支持 Ollama、llama.cpp 和 vLLM，并具备自动回退到云端提供商的能力。该技能使智能体能够利用本地 GPU/CPU 推理，同时通过智能回退保持可靠性。

用途

该技能适用于以下场景：

本地运行 LLM 推理以保护隐私（数据不离开本机）
使用云端 API 不可用的模型（如微调模型、Llama 变体）
降低高频任务的 API 成本
离线或网络不稳定时工作
需要低延迟的交互式任务响应

主要能力

连接本地 LLM 端点：Ollama、llama.cpp、vLLM
自动提供商回退：按顺序尝试本地提供商，失败时回退到云端提供商（如果启用）
支持查询、自定义参数、列出模型、健康检查、流式响应
可作为库集成到 Node.js 项目
输出 JSON 格式结果，包含成功状态、提供商、模型、响应、token 数、耗时等

使用方式

设置

如果 Ollama 已在运行，无需额外设置。否则：

Ollama 设置

# 安装 Ollama
curl -fsSL https://ollama.com/install.sh | sh

# 拉取模型
ollama pull llama3.2

# 启动服务器（默认：http://localhost:11434）
ollama serve

llama.cpp 服务器设置

# 构建 llama-server
make llama-server

# 启动服务器
llama-server -hf ggml-org/gpt-oss-20b-GGUF -c 133000 --host 127.0.0.1 --port 8080

vLLM 服务器设置

# 安装 vLLM
pip install vllm

# 启动服务器
vllm serve meta-llama/Llama-3.1-8B-Instruct

使用

查询本地模型：

node /job/.pi/skills/local-llm-provider/query.js "What is 2+2?" --model llama3.2

使用自定义参数查询：

node /job/.pi/skills/local-llm-provider/query.js "Explain quantum computing" --model mixtral --temp 0.8 --max-tokens 500

列出可用模型：

node /job/.pi/skills/local-llm-provider/list-models.js

检查服务器健康：

node /job/.pi/skills/local-llm-provider/health.js

流式响应：

node /job/.pi/skills/local-llm-provider/query.js "Tell me a story" --stream

配置

在技能目录中创建 config.json 以持久化设置：

{
  "providers": [
    {
      "name": "ollama",
      "url": "http://localhost:11434",
      "enabled": true,
      "fallback_order": 1
    },
    {
      "name": "llamacpp",
      "url": "http://localhost:8080/v1",
      "enabled": false,
      "fallback_order": 2
    },
    {
      "name": "vllm",
      "url": "http://localhost:8000/v1",
      "enabled": false,
      "fallback_order": 3
    }
  ],
  "default_model": "llama3.2",
  "fallback_to_cloud": true,
  "cloud_provider": "anthropic",
  "timeout_ms": 120000
}

提供商回退

该技能实现智能回退：

主要：首先尝试本地 Ollama
次要：尝试 llama.cpp 服务器
第三：尝试 vLLM 服务器
回退：使用云端提供商（如果启用）

每个提供商失败会触发自动重试下一个可用提供商。

支持的模型

Ollama

llama3.2, llama3.1, llama3
mistral, mixtral
qwen2.5, qwen2
phi3, phi4
gemma2, gemma
codellama
以及更多

llama.cpp

任何 GGUF 格式模型
Mistral 变体
Llama 变体
Qwen 变体

vLLM

Llama 3.1, 3.0
Mistral
Qwen
任何 HuggingFace 模型

API 集成

作为库使用：

const { LocalLLMProvider } = require('./provider.js');

const provider = new LocalLLMProvider({
  providers: [
    { name: 'ollama', url: 'http://localhost:11434', enabled: true },
    { name: 'anthropic', api_key: process.env.ANTHROPIC_API_KEY, enabled: false }
  ],
  default_model: 'llama3.2',
  fallback_to_cloud: true
});

const response = await provider.complete('Hello, how are you?');
console.log(response);

输出格式

查询返回 JSON：

{
  "success": true,
  "provider": "ollama",
  "model": "llama3.2",
  "response": "I'm doing well, thank you for asking!",
  "tokens": 42,
  "duration_ms": 1500,
  "done": true
}

流式时：

{
  "success": true,
  "provider": "ollama",
  "model": "llama3.2",
  "response": "I",
  "tokens": 1,
  "done": false
}

回退失败时：

{
  "success": false,
  "error": "All providers failed",
  "providers_tried": ["ollama", "llamacpp"],
  "last_error": "Connection refused"
}

环境变量

变量	描述	默认值
OLLAMA_BASE_URL	Ollama 服务器 URL	http://localhost:11434
LLAMACPP_BASE_URL	llama.cpp 服务器 URL	http://localhost:8080/v1
VLLM_BASE_URL	vLLM 服务器 URL	http://localhost:8000/v1
LOCAL_LLM_DEFAULT_MODEL	默认使用的模型	llama3.2

适用场景

隐私敏感任务：数据不离开本机
使用云端不可用的模型
高频任务降低成本
离线或网络不稳定环境
需要低延迟的交互式任务

限制

需要本地服务器运行
模型质量取决于本地硬件
并非所有模型支持所有功能（如函数调用）
部分提供商 API 格式不同

提示

最佳性能：使用 Ollama 并启用 GPU 加速
多样性：拉取多个模型（ollama pull mixtral）
隐私：始终优先使用本地提供商
可靠性：对关键任务保持云端回退启用
速度：简单任务使用较小模型（7B），复杂推理使用较大模型（70B）