aisdk：在 R console 聊天，让 AI 干活

关键词：R、RStudio、AI SDK、智能体、API Key、BASE URL、console_chat、AI 辅助写代码

1. aisdk 是什么？#

aisdk 全称是 The AI SDK for R，是 YuLab-SMU 开发的 R 包，用于在 R 语言中构建 AI 驱动应用。

• GitHub：https://github.com/YuLab-SMU/aisdk/
• 官方文档：https://yulab-smu.top/aisdk/

一句话理解：

aisdk 可以把 AI 助手搬进 R console，让你在 RStudio 里直接聊天、写代码、调试、画图和运行分析任务。

2. 适合谁用？#

尤其适合：

• 经常使用 R / RStudio 的生信学习者；
• 想让 AI 帮忙写 R 代码、解释报错、画图的人；
• 想在 RMarkdown、Quarto、Shiny 中接入 AI 的用户；
• 想尝试 Agent，但又不想离开 R 工作环境的人。

3. 核心功能速览#

对新手来说，先掌握这一条路线就够了：

安装 aisdk → 配置 API_KEY / BASE_URL / MODEL → console_chat() → 让 AI 帮你写 R 代码

4. 安装 aisdk#

建议安装 GitHub 最新版：

# 如果没有 devtools，先安装
install.packages("devtools")

# 从 GitHub 安装 aisdk
devtools::install_github("YuLab-SMU/aisdk")

library(aisdk)
packageVersion("aisdk")

教程原文中示例版本是 1.1.2，GitHub 主页中已经能看到更高版本信息。实际版本以本地安装结果为准。

5. 使用前必须准备的 3 个东西#

调用 AI 模型通常需要：

示例：

OPENAI_API_KEY=sk-xxxxxxxxxxxxxxxx
OPENAI_BASE_URL=https://api.deepseek.com
OPENAI_MODEL=deepseek-chat

注意API Key 不要公开发到微信群、公众号、GitHub、截图或公开 Obsidian 库里。

6. 当前已跑通的中转 API 配置示例#

这次实际测试中，之前报错的原因是：

Sys.getenv("OPENAI_BASE_URL")
# [1] ""

Sys.getenv("OPENAI_MODEL")
# [1] ""

也就是 API Key 有了，但 BASE_URL 和 MODEL 没有配置。

后来临时设置后成功跑通：

Sys.setenv(OPENAI_BASE_URL = "https://your-api-host.example/v1")
Sys.setenv(OPENAI_MODEL = "gpt-5.5")

library(aisdk)

set_model("openai:gpt-5.5")

response <- generate_text(prompt = "用中文简单解释 testthat 是干什么的。")
cat(response$text)

成功返回了关于 testthat 的中文解释，说明：

aisdk 可以通过 OpenAI-compatible 中转接口正常调用模型；之前的 Network error 主要是因为 OPENAI_BASE_URL 没设。

7. 建议写入 .Renviron，避免每次手动设置#

临时设置 Sys.setenv() 只对当前 R session 有效。建议写入 .Renviron：

file.edit("~/.Renviron")

加入：

OPENAI_API_KEY=你的API_KEY
OPENAI_BASE_URL=https://your-api-host.example/v1
OPENAI_MODEL=gpt-5.5

保存后重启 R session，再检查：

Sys.getenv("OPENAI_API_KEY")
Sys.getenv("OPENAI_BASE_URL")
Sys.getenv("OPENAI_MODEL")

如果能看到对应值，之后就可以直接：

library(aisdk)
set_model("openai:gpt-5.5")

response <- generate_text(prompt = "你好，请用中文介绍 aisdk。")
cat(response$text)

8. 在 RStudio 中进入 AI 对话#

最适合新手的入口是 console_chat()：

rm(list = ls())
library(aisdk)

console_chat()

进入后常用命令：

/help   # 查看帮助
/model  # 配置或切换模型
/quit   # 退出会话

可以直接输入自然语言任务，例如：

使用 ggplot2 绘制两个基因表达水平的相关性散点图，数据随机生成，有 60 个样本。

也可以继续让它：

保存使用的代码和图片，最后将图片展示出来。

9. 编程式调用：generate_text()#

如果不想进入聊天，而是在 R 脚本中直接调用模型，可以用：

library(aisdk)

set_model("openai:gpt-5.5")

response <- generate_text(prompt = "用中文解释 testthat 是干什么的。")
cat(response$text)

这种方式适合：

• 写自动化脚本；
• 在 RMarkdown / Quarto 中调用 AI；
• 在 Shiny 应用中加入 AI 功能。

10. 出错排查清单#

如果出现：

Network error, retrying in 2000 ms...

优先检查：

Sys.getenv("OPENAI_API_KEY")
Sys.getenv("OPENAI_BASE_URL")
Sys.getenv("OPENAI_MODEL")
model()

常见原因：

11. ask_ai：R 报错后让 AI 自动看上下文#

ask_ai() 是一个很实用的功能。R 报错后，它可以收集：

• 最近错误；
• traceback；
• warnings；
• 当前 RStudio 文档；
• session 信息；
• workspace 对象摘要。

示例：

# 只预览即将发送给 AI 的上下文
ask_ai(show_context = TRUE)

# 真正打开 AI 对话
ask_ai()

适合用来让 AI 帮忙解释 R 报错。

12. Agent 和工具调用，先知道即可#

aisdk 还支持构建 Agent，把 R 函数变成 AI 可调用工具。例如：

calc_tool <- tool(
  name = "add_numbers",
  description = "Adds two numbers together",
  execute = function(a, b) a + b
)

agent <- create_agent(
  name = "Mathematician",
  description = "Solve math problems accurately",
  system_prompt = "You are a helpful mathematician.",
  tools = list(calc_tool)
)

result <- agent$run("What is 1234 + 5678?", model = model)
render_text(result)

新手阶段不用急着掌握，先把 console_chat() 和 generate_text() 跑通即可。

13. 推荐入门流程#

1. 安装最新版 aisdk；
2. 准备 API Key；
3. 配置 OPENAI_BASE_URL 和 OPENAI_MODEL；
4. 用 generate_text() 测试是否能正常返回；
5. 再进入 console_chat()；
6. 先用模拟数据测试画图、保存文件、解释代码；
7. 遇到 R 报错时尝试 ask_ai()；
8. 熟悉后再尝试真实生信分析任务。

14. 可以用它做什么？#

• 让 AI 写 ggplot2 代码；
• 让 AI 解释 R 报错；
• 让 AI 辅助 GEO 数据分析；
• 让 AI 帮忙整理 RMarkdown / Quarto 报告；
• 让 AI 辅助 Seurat、DESeq2、limma 等生信包学习；
• 把常用 R 函数封装成 AI 工具；
• 进阶后构建面向生信分析的 R Agent。

15. 相关链接#

• aisdk GitHub：https://github.com/YuLab-SMU/aisdk/
• aisdk 文档：https://yulab-smu.top/aisdk/
• DeepSeek 官网：https://www.deepseek.com/
• DeepSeek API 文档：https://api-docs.deepseek.com/zh-cn/

16. 进阶用法：从聊天工具升级为 R 里的 Agent 框架#

这一节根据 aisdk GitHub README 与官方 vignettes 补充，适合在 console_chat() 和 generate_text() 跑通之后再看。

16.1 console_chat 的高级命令#

新版 console_chat() 不只是简单聊天窗口，而是基于 ChatSession 的终端 Agent 界面。除了基础的 /help、/model、/quit，还可以用这些命令管理会话、检查工具调用和查看用量：

/history              # 查看当前会话历史
/stats                # 查看 token 和工具使用统计
/clear                # 清空当前对话历史
/save analysis.rds    # 保存当前会话
/load analysis.rds    # 恢复之前保存的会话
/stream on            # 开启流式输出
/stream off           # 关闭流式输出
/inspect on           # 进入检查模式
/inspect turn         # 查看最近一轮对话细节
/inspect tool <index> # 查看某个工具调用细节
/debug on             # 打开调试模式
/debug off            # 关闭调试模式
/local on             # 允许本地执行/修改工作区对象，谨慎使用
/local off            # 关闭本地执行模式

和前面“如何查看上下文窗口和用量”的问题相关，优先记住：

/stats
/history
/inspect turn

• /stats：查看本会话 token / tool usage 统计；
• /history：查看当前会话历史，判断上下文里累积了哪些内容；
• /inspect turn：检查最近一轮输入、输出、工具调用、警告和耗时。

推荐日常工作流：

library(aisdk)
set_model("openai:gpt-4o-mini")

console_chat()

进入后：

/inspect on
/stats

平时用 clean 模式聊天，只有在工具调用复杂、出错或想看 token / 工具统计时再切到 inspect/debug。

16.2 ChatSession：有状态多轮对话#

如果想在 R 脚本、Shiny 或 Quarto 里管理连续对话，不一定要开 console_chat()，可以直接用 ChatSession：

library(aisdk)

model <- create_openai()$language_model("gpt-4o")

session <- ChatSession$new(
  model = model,
  system_prompt = "You are a helpful R and bioinformatics assistant."
)

response1 <- session$send("请解释 Seurat 对象里的 assay 是什么。")
cat(response1$text)

# 第二轮会自动带上前面的历史
response2 <- session$send("那 RNA assay 和 integrated assay 有什么区别？")
cat(response2$text)

中途也可以切换模型，但保留会话历史：

session$switch_model("anthropic:claude-3-5-sonnet-20241022")
session$send("请把上面的解释改成适合新手看的版本。")

会话可以保存和恢复：

session$save("my_aisdk_session.json")

new_session <- ChatSession$new(model = model)
new_session$restore("my_aisdk_session.json")

16.3 工具调用：把 R 函数变成 AI 可用工具#

aisdk 的核心进阶能力之一，是把 R 函数包装成 tool，让模型在需要时自动调用。

library(aisdk)

calc_tool <- tool(
  name = "calculate",
  description = "Perform a mathematical calculation on two numbers",
  parameters = z_object(
    a = z_number("The first number"),
    b = z_number("The second number"),
    operation = z_enum(c("add", "subtract", "multiply", "divide"), "The operator")
  ),
  execute = function(args) {
    switch(
      args$operation,
      add = args$a + args$b,
      subtract = args$a - args$b,
      multiply = args$a * args$b,
      divide = if (args$b != 0) args$a / args$b else "Error: Division by zero"
    )
  }
)

model <- create_openai()$language_model("gpt-4o")

result <- generate_text(
  model = model,
  prompt = "What is 123 multiplied by 456?",
  tools = list(calc_tool),
  max_steps = 3
)

cat(result$text)

对生信分析来说，可以把一些高频操作封装成工具，例如：

• 读取表达矩阵；
• 检查 Seurat 对象结构；
• 统计 metadata 分组；
• 执行差异分析；
• 生成标准 ggplot2 图；
• 保存结果表和图片。

注意：会写文件、删文件、运行系统命令的工具要格外谨慎，最好先从只读工具开始。

16.4 Agent：带人设、工具和任务能力的 AI 工作者#

Agent 可以理解为“带专业角色和工具箱的 AI”。

library(aisdk)

researcher <- create_agent(
  name = "Researcher",
  description = "Finds and summarizes information on specific topics",
  system_prompt = "You are a professional researcher. Provide citations for your findings."
)

model <- create_openai()$language_model("gpt-4o")

result <- researcher$run(
  task = "Summarize common QC steps in single-cell RNA-seq analysis.",
  model = model
)

cat(result$text)

aisdk 还提供一些预设 Agent：

coder <- create_coder_agent()          # 写代码/改代码
visualizer <- create_visualizer_agent()# 偏 ggplot2 可视化
planner <- create_planner_agent()      # 拆解复杂任务

Agent 默认偏“能力配置”，如果想让 Agent 记住上下文，可以从 Agent 创建 session：

session <- researcher$create_session(model = model)
session$send("先总结 Seurat 标准流程。")
session$send("再把它改成适合口腔鳞癌单细胞项目的流程。")

16.5 多 Agent 协作：Manager + Worker#

更复杂的任务可以让多个 Agent 分工。例如：Planner 负责拆任务，Coder 负责写 R 代码，Visualizer 负责画图。

coder <- create_coder_agent()
visualizer <- create_visualizer_agent()

registry <- create_agent_registry(list(coder, visualizer))

session <- ChatSession$new(model = model)
flow <- Flow$new(session = session, registry = registry)

manager <- create_agent(
  name = "Manager",
  description = "Orchestrates data analysis tasks",
  system_prompt = "You are a project manager. Delegate tasks to Coder or Visualizer as needed."
)

result <- flow$run(
  agent = manager,
  task = "Load the iris dataset, calculate means by species, and plot the result."
)

这个模式适合后续扩展成“生信分析助手”：

Manager：理解任务和分派
Coder：写 R/Seurat/DESeq2 代码
Visualizer：生成图
Reviewer：检查统计和结果解释

16.6 结构化输出：让 AI 返回 list / data.frame，而不是一段散文#

如果希望 AI 输出可以直接进入 R 流程，优先使用 generate_object() 加 schema。

library(aisdk)

recipe_schema <- z_object(
  name = z_string("Name of the dish"),
  ingredients = z_array(z_string(), "List of ingredients"),
  prep_time_mins = z_integer("Preparation time in minutes")
)

result <- generate_object(
  model = model,
  prompt = "Give me a simple recipe for a classic Omelette.",
  schema = recipe_schema
)

str(result$object)

提取表格数据时可以用 z_dataframe()：

gene_schema <- z_dataframe(
  gene_symbol = z_string("Standard gene symbol"),
  fold_change = z_number("Log2 fold change value"),
  p_value = z_number("Adjusted p-value")
)

result <- generate_object(
  model = model,
  prompt = "Extract gene expression data: BRCA1 FC=2.5 p=0.01; TP53 FC=-1.2 p=0.04.",
  schema = gene_schema
)

df <- dplyr::bind_rows(result$object)
print(df)

生信场景里特别适合让 AI 返回：

• 基因列表；
• marker 表格；
• 通路富集摘要；
• 样本分组信息；
• 文献中提取的细胞类型、疾病、方法、结论字段。

16.7 自定义 Provider：接入 OpenAI-compatible 中转或本地模型#

如果服务商兼容 OpenAI / Anthropic 格式，但 aisdk 没有内置 provider，可以用 create_custom_provider()。

library(aisdk)

custom_provider <- create_custom_provider(
  provider_name = "my_custom_proxy",
  base_url = "https://my-custom-proxy.com/v1",
  api_key = Sys.getenv("CUSTOM_API_KEY"),
  api_format = "chat_completions"
)

custom_model <- custom_provider$language_model("my-custom-model-id")

response <- generate_text(
  model = custom_model,
  prompt = "你好，请用中文介绍一下 aisdk。"
)

cat(response$text)

api_format 可根据服务商接口选择，例如：

chat_completions      # OpenAI chat completions 兼容格式
anthropic_messages    # Anthropic messages 兼容格式
responses             # OpenAI responses 兼容格式

16.8 AIHubMix 原生接口：Claude 缓存和 Gemini 结构化能力#

README 里提到，AIHubMix 不只是 OpenAI-compatible，还可以通过原生 Anthropic / Gemini 接口释放更多能力，例如 Claude prompt caching 或 Gemini structured outputs：

library(aisdk)

# Claude / Anthropic 格式，支持扩展缓存能力
aihubmix_claude <- create_aihubmix_anthropic(extended_caching = TRUE)
claude_model <- aihubmix_claude$language_model("claude-3-5-sonnet-20241022")

# Gemini 原生格式
aihubmix_gemini <- create_aihubmix_gemini()
gemini_model <- aihubmix_gemini$language_model("gemini-2.5-flash")

适合场景：

• 长系统提示词或长背景资料反复复用；
• 想用 Claude prompt caching 降低重复上下文成本；
• 想用 Gemini 原生结构化输出或多模态能力。

16.9 多模态：图片理解和结构化提取#

aisdk 也支持图片输入。可以让模型分析截图、图表、实验图片，或者从图片中抽取结构化字段。

典型模式：

image_schema <- z_object(
  title = z_string("Figure title or main topic"),
  x_axis = z_string("X axis label"),
  y_axis = z_string("Y axis label"),
  conclusion = z_string("Main conclusion from the figure")
)

result <- extract_from_image(
  model = create_openai()$language_model("gpt-4o"),
  image = "figure.png",
  schema = image_schema
)

str(result$object)

可用于：

• 读取论文图；
• 检查火山图、UMAP、热图；
• 从截图里提取报错信息；
• 把图片里的表格或字段转成 R list / data.frame。

16.10 Shiny / RMarkdown / Quarto 集成#

Shiny 聊天界面

aisdk 可以把 ChatSession 接到 Shiny UI 里。推荐先在终端用 console_chat(chat) 验证模型和工具，再接入 Shiny。

library(shiny)
library(aisdk)

chat <- create_chat_session(
  model = "openai:gpt-4o",
  tools = list(calc_tool)
)

# 可选：先在 R console 里测试
# console_chat(chat)

ui <- fluidPage(aiChatUI("chat"))

server <- function(input, output, session) {
  aiChatServer(
    "chat",
    session = chat,
    show_thinking = TRUE,
    debug = FALSE
  )
}

shinyApp(ui, server)

RMarkdown / Quarto AI 代码块

在 RMarkdown / Quarto 中可以注册 {ai} engine，让 AI 根据上下文生成并执行 R 代码。

library(aisdk)
register_ai_engine()

RMarkdown 中：

```{ai}
Create a scatter plot of mpg vs wt from the mtcars dataset,
colored by the number of cylinders using ggplot2.
```

Quarto 中推荐写法：

```{r}
#| engine: ai
#| eval: true
Create a scatter plot of mpg vs wt from the mtcars dataset,
colored by the number of cylinders using ggplot2.
```

如果前面的代码块里已经有对象，AI engine 可以自动根据 prompt 识别相关对象并发送摘要；也可以手动控制：

#| context: my_data

或关闭上下文：

#| context: false

16.11 MCP：把外部工具服务器接入 aisdk Agent#

aisdk 提供 MCP client，可以把外部 MCP server 暴露的工具转成 aisdk 工具。

library(aisdk)

sqlite_client <- create_mcp_client(
  command = "npx",
  args = c("-y", "@modelcontextprotocol/server-sqlite", "--db", "my_data.db")
)

sqlite_client$is_alive()

# 查看 MCP server 提供哪些工具
tools <- sqlite_client$list_tools()

# 转成 aisdk 可用工具
sdk_tools <- sqlite_client$as_sdk_tools()

response <- generate_text(
  model = model,
  prompt = "Query the iris table and tell me the average Sepal.Length.",
  tools = sdk_tools
)

cat(response$text)

# 用完关闭
sqlite_client$close()

可扩展方向：

• 接数据库 MCP；
• 接文件系统 MCP；
• 接文献检索 MCP；
• 接实验记录或 ELN MCP；
• 接本地生信 pipeline 工具。

16.12 Telemetry、权限 Hook 和工具缓存#

生产化或长流程任务中，可以用 telemetry / hooks 追踪调用、控制权限、缓存慢工具。

library(aisdk)

telemetry <- create_telemetry(trace_id = "request-123")
hooks <- telemetry$as_hooks()

generate_text(
  model = "openai:gpt-4o",
  prompt = "Hello",
  hooks = hooks
)

对敏感工具调用加权限控制：

perm_hook <- create_permission_hook(
  mode = "escalate",
  allowlist = c("read_file")
)

hooks$hooks$on_tool_approval <- perm_hook$hooks$on_tool_approval

缓存耗时工具：

slow_tool <- tool(
  name = "slow_tool",
  description = "Sleep 5 seconds and return x",
  parameters = z_object(x = z_number("Input number")),
  execute = function(args) {
    Sys.sleep(5)
    args$x
  }
)

fast_tool <- cache_tool(slow_tool)

fast_tool$run(list(x = 1)) # 第一次慢
fast_tool$run(list(x = 1)) # 第二次命中缓存

16.13 推荐的进阶学习路线#

如果只是为了生信日常辅助，建议按这个顺序学习：

1. console_chat()：熟悉 /stats、/history、/inspect、/save、/load；
2. ChatSession：掌握可保存、可恢复的多轮对话；
3. tool()：把自己的 R 函数封装成 AI 工具；
4. create_agent()：给工具加角色和系统提示词；
5. generate_object()：让 AI 输出可直接进入 R 的结构化结果；
6. Shiny / Quarto 集成：做交互式分析助手或自动报告；
7. MCP / multi-agent / hooks：最后再考虑工程化和自动化流程。

一个面向口腔生信项目的理想形态：

console_chat 负责交互入口
ChatSession 负责记忆和状态
Tools 负责执行 R/Seurat/DESeq2/ggplot2 操作
Agent 负责专业角色和任务规划
generate_object 负责结构化提取 marker、通路、文献信息
Shiny/Quarto 负责最终报告和界面

---

原始教程摘要#

这篇教程的核心经验是：作者在 YH 大佬指点下，尝试配置 aisdk，成功在 RStudio 的 R console 里进入 AI 对话，并让 AI 使用 ggplot2 生成基因表达相关性散点图、保存代码和图片。整体体验顺滑，适合作为 R 用户接触 AI Agent 的入门案例。