ellmer

ellmer 让在 R 中使用大型语言模型（LLM）变得简单易行。它支持多种 LLM 提供商，并实现了丰富的功能，包括流式输出、工具/函数调用、结构化数据提取等。

ellmer 是 Posit 公司开发的多个 LLM 相关包之一：

• 如果您正在寻找 Python 中类似的功能，请查看 chatlas！
• 想评估您的 LLM 吗？试试 vitals。
• 需要 RAG 技术吗？可以看看 ragnar。
• 想构建一个美观的 LLM 驱动聊天机器人吗？不妨考虑 shinychat。
• 如果您正在使用 MCP，可以查看 mcptools。

安装

您可以从 CRAN 安装 ellmer：

install.packages("ellmer")

支持的提供商

ellmer 支持多种模型提供商：

• Anthropic 的 Claude：chat_anthropic()。
• AWS Bedrock：chat_aws_bedrock()。
• Azure OpenAI：chat_azure_openai()。
• Cloudflare：chat_cloudflare()。
• Databricks：chat_databricks()。
• DeepSeek：chat_deepseek()。
• GitHub 模型市场：chat_github()。
• Google Gemini/Vertex AI：chat_google_gemini()、 chat_google_vertex()。
• Groq：chat_groq()。
• Hugging Face：chat_huggingface()。
• Mistral：chat_mistral()。
• Ollama：chat_ollama()。
• OpenAI：chat_openai()。
• OpenRouter：chat_openrouter()。
• perplexity.ai：chat_perplexity()。
• Snowflake Cortex：chat_snowflake() 和 chat_cortex_analyst()。
• VLLM：chat_vllm()。

提供商与模型选择

如果您在组织内部使用 ellmer，可能会受到公司政策限制，只能使用大型云服务商提供的模型，例如 chat_azure_openai()、chat_aws_bedrock()、chat_databricks() 或 chat_snowflake()。

如果您是出于个人探索目的使用 ellmer，则有更大的自由度。以下是一些建议，帮助您快速上手：

• 可以从 chat_openai() 或 chat_anthropic() 开始。chat_openai() 默认使用 GPT-4.1，但您也可以选择更便宜、更快的模型，如 model = "gpt-4-1-nano"，或者使用 model = "o3" 进行更复杂的推理。chat_anthropic() 也是一个不错的选择，默认使用 Claude 4.0 Sonnet，我们发现它在编写 R 代码方面表现尤为出色。

• chat_google_gemini() 是一款强大的模型，且提供慷慨的免费额度（缺点是您的数据会被用于改进模型），因此如果您不想花钱，这是一个很好的起点。

• chat_ollama() 使用 Ollama，允许您在本地运行模型。虽然本地运行的最大模型性能不如云端最先进的模型，但它不会共享您的数据，而且几乎是免费的。

身份验证

不同提供商的身份验证方式略有不同。一些主流提供商（如 OpenAI 和 Anthropic）需要您获取 API 密钥。我们建议将密钥保存在环境变量中，而不是直接写入代码中。此外，如果您将使用 ellmer 的应用程序或报告部署到其他系统，也需要确保这些环境变量在目标系统中可用。

ellmer 还能自动检测许多基于 OAuth 或 IAM 的凭据，这些凭据通常由大型云服务商使用（目前支持 chat_azure_openai()、chat_aws_bedrock()、chat_databricks() 和 chat_snowflake()）。这包括由 Posit Workbench 和 Posit Connect 管理的平台凭据。

如果您发现 ellmer 无法检测到某些云服务商的凭据，请随时提交问题，我们很乐意根据需要添加更多身份验证机制。

使用 ellmer

根据您是以交互式还是编程方式使用 ellmer，可以采用不同的方法。所有操作都始于创建一个新的聊天对象：

library(ellmer)

chat <- chat_openai("保持简洁", model = "gpt-4o-mini")

聊天对象是具有状态的 R6 对象：它们会保留对话上下文，因此每次新的查询都会基于之前的对话内容。您可以通过 $ 调用其方法。

交互式聊天控制台

使用 ellmer 最具交互性、最不需编程的方式，就是在 R 控制台或浏览器中直接与模型对话，只需调用 live_console(chat) 或 live_browser() 即可：

live_console(chat)
#> ╔════════════════════════════════════════════════════════╗
#> ║  进入聊天控制台。多行输入请使用 """。  ║
#> ║  按 Ctrl+C 退出。                                 ║
#> ╚════════════════════════════════════════════════════════╝
#> >>> R 的最初创造者是谁？
#> R 最初是由新西兰奥克兰大学的 Ross Ihaka 和 Robert Gentleman 创建的。
#>
#> >>> 那是什么时候？
#> R 最早于 1995 年发布。其开发工作则开始于再往前几年，即 20 世纪 90 年代初。

请注意，聊天对象会保留状态。因此，当您进入聊天控制台时，之前与该聊天对象的所有交互仍然属于当前对话的一部分；而您在聊天控制台中的任何互动，在返回 R 提示符后也会继续存在。无论您使用哪种聊天函数，情况都是如此。

交互式方法调用

第二种最交互式的聊天方式是调用 chat() 方法：

chat$chat("哪些早期语言对 R 影响最大？")
#> R 主要受到 S 语言的影响，S 语言是由贝尔实验室开发的。 
#> 其他值得注意的影响还包括：
#> 
#> 1. **Scheme** - 提供了函数式编程的概念。
#> 2. **LISP** - 拥有强大的数据操作特性。
#> 3. **C** - 提升了性能并提供了系统级访问能力。
#> 4. **Fortran** - 在数值和统计计算方面发挥了重要作用。
#> 
#> 这些语言共同塑造了 R 的语法、数据结构以及函数式编程能力。

如果你在全局环境中初始化聊天对象，chat 方法会将响应流式输出到控制台。当整个响应接收完毕后，它还会以字符向量的形式（不可见地）返回。这在你希望实时查看响应内容，但又不想进入聊天控制台时非常有用。

如果你想就一张图片提问，可以使用 content_image_file() 和/或 content_image_url() 传递一个或多个额外的输入参数：

chat$chat(
  content_image_url("https://www.r-project.org/Rlogo.png"),
  "你能解释一下这个标志吗？"
)
#> 该标志由一个蓝色的风格化字母“R”组成，周围环绕着灰色的椭圆形。 
#> 设计体现了 R 编程语言的特点，R 广泛用于统计计算和图形绘制。 
#> 颜色的选择通常象征着清晰与专业性，这也符合 R 在数据分析和研究中的应用。 
#> 整体标志传达了该语言专注于数据可视化和统计方法的核心理念。

流式输出与捕获

在大多数情况下，ellmer 会将输出流式显示在控制台上。你可以通过在创建聊天对象时或调用 $chat() 时设置 echo 参数来控制这一行为。将 echo = "none" 设置为返回字符串：

my_function <- function() {
  chat <- chat_openai("尽量简洁", model = "gpt-4o-mini", echo = "none")
  chat$chat("6 乘以 7 等于多少？")
}
str(my_function())
#>  'ellmer_output' chr "6 乘以 7 等于 42。"

如果需要，你也可以手动通过 echo 参数控制这一行为。这在使用 ellmer 进行编程时非常有用，尤其是在结果并非 intended for human consumption，或者你希望在显示之前先处理响应的情况下。

学习更多

ellmer 自带一系列 vignette，帮助你进一步学习：

• 在 vignette("ellmer") 中学习关键术语并查看示例用法。
• 在 vignette("prompt-design") 中学习如何设计提示词。
• 在 vignette("tool-calling") 中了解工具/函数调用。
• 在 vignette("structured-data") 中学习如何提取结构化数据。
• 在 vignette("streaming-async") 中了解流式传输和异步 API。

ellmer 快速上手指南

ellmer 是一个专为 R 语言设计的开源包，旨在简化大语言模型（LLM）的集成与使用。它支持包括 OpenAI、Anthropic、Azure、AWS 在内的众多主流模型提供商，并提供流式输出、工具调用及结构化数据提取等丰富功能。

环境准备

• 系统要求：需安装 R (建议版本 4.1+) 和 RStudio（推荐）。
• 前置依赖：
  • 确保已配置好网络连接，能够访问所选 LLM 提供商的 API 服务。
  • 认证凭证：大多数提供商（如 OpenAI, Anthropic）需要 API Key。建议将其设置为环境变量（例如 OPENAI_API_KEY），而非硬编码在脚本中。
  • 若使用国内云厂商或特定代理网络，请确保环境变量中已配置相应的代理设置。

安装步骤

你可以直接从 CRAN 安装稳定版：

install.packages("ellmer")

若需体验最新开发特性，也可从 GitHub 安装（需先安装 remotes 包）：

# install.packages("remotes")
remotes::install_github("tidyverse/ellmer")

基本使用

1. 初始化聊天对象

加载库并创建一个聊天对象。以下示例以 OpenAI 为例（需确保环境变量中已设置 OPENAI_API_KEY）：

library(ellmer)

# 创建聊天对象，指定系统提示词和模型
chat <- chat_openai("Be terse", model = "gpt-4o-mini")

提示：ellmer 支持多种提供商，只需替换函数名即可，例如 chat_anthropic(), chat_azure_openai(), chat_ollama() 等。

2. 交互式对话

最直接的方式是在控制台进行实时对话。输入 live_console(chat) 即可进入交互模式：

live_console(chat)
# 进入后直接输入问题，输入 """ 可进行多行输入，Ctrl+C 退出

3. 编程式调用

在脚本中通过 $chat() 方法发送消息。默认情况下，回复会流式打印到控制台，并隐形返回结果字符串：

response <- chat$chat("R 语言的主要前身是什么？")
# 输出将直接显示在控制台，同时结果存储在 response 变量中

处理图片输入： 你可以结合 content_image_url() 或 content_image_file() 发送包含图片的请求：

chat$chat(
  content_image_url("https://www.r-project.org/Rlogo.png"),
  "请解释这个 Logo 的含义"
)

4. 控制输出模式

如果你希望在函数中捕获返回值而不直接打印到控制台（例如用于后续数据处理），可设置 echo = "none"：

my_function <- function() {
  # 创建时禁止自动打印
  chat_silent <- chat_openai("Be terse", model = "gpt-4o-mini", echo = "none")
  result <- chat_silent$chat("6 乘以 7 等于多少？")
  return(result)
}

str(my_function())
# 输出：'ellmer_output' chr "6 times 7 is 42."