Suna本地部署详细教程

原创已于 2025-08-08 14:17:19 修改 · 2k 阅读

27 ·

CC 4.0 BY-SA版权

文章标签：

#人工智能

于 2025-06-19 13:19:14 首次发布

人工智能同时被 3 个专栏收录

145 篇文章

订阅专栏

智能体

3 篇文章

订阅专栏

suna

1 篇文章

订阅专栏

该文章已生成可运行项目，

一、安装基础环境

# 1、创建环境
conda create -n suna python==3.11.7

# 2、激活虚拟环境
conda activate suna

# 3、安装jupyter和ipykernel
pip install jupyter ipykernel

# 4、将虚拟环境添加到jupyter
# python -m ipykernel install --user --name=myenv --display-name="Python (myenv)"
python -m ipykernel install --user --name=suna

二、安装suna环境

切换到源码路径下
cd /Users/dcs/study/Suna修改后项目源码/suna/backend


然后使用pip install，安装Suna项目依赖
pip install -r requirements.txt

安装完成后，我们进入项目前端文件夹（frontend）
然后使用npm install安装前端依赖，
cd /Users/dcs/study/Suna修改后项目源码/suna/frontend

npm install

三、配置Suna项目后端

为了让 Suna 项目具备完整的功能能力，后端需要集成并配置多个核心组件。这些组件为智能体的网络感知、数据抓取、任务执行和持久化存储等功能提供支持。整个配置流程共包括四个关键步骤，分别对应四个重要模块：

配置 1：Tavily API-KEY —— 开启网络搜索功能

Tavily 是一个支持智能搜索请求的 API 服务，能够帮助智能体通过自然语言查询获取实时的网页搜索结果。
在 Suna 中，Tavily 的接入主要用于为智能体提供“联网搜索”能力，特别适用于需要获取最新信息的 RAG（Retrieval-Augmented Generation）场景。
配置 2：Firecrawl API-KEY —— 开启网页爬虫功能

Firecrawl 是一个轻量级的网页爬虫服务，它可以提取网页的文本内容、元信息甚至嵌入结构化数据。
在 Suna 中，Firecrawl 的接入使得智能体可以针对特定网页进行内容爬取和语义理解，为深度问答、内容分析等任务提供支持。
配置 3：Daytona —— 开启沙盒环境支持

Daytona 是一个可供开发者远程部署并运行代码的云端开发环境。通过接入 Daytona，Suna 的智能体可以在隔离的沙盒中运行代码、调试任务或部署服务，从而实现更强的“Agent 执行能力”。
配置 4：Supabase —— 启用完整后端数据支持

Supabase 是一个开源后端服务平台，提供数据库、认证、存储等多项功能。在 Suna 中，Supabase 被用作数据持久化、用户管理、运行日志记录等关键功能的后端支持。

配置1、tavily API-KEY：开启网络搜索功能

第一步是获取搜索引擎 Tavily 的 API Key。请前往 Tavily 官方网站（ Tavily - The Web Access Layer for AI Agents），完成账户注册流程。注册成功后，即可在用户控制台中生成并获取专属的 API Key，用于在 Suna 项目中启用联网搜索功能。

接下来，进入 Suna 项目的后端目录（backend 文件夹），使用文本编辑器打开 .env 文件。该文件是用于配置后端环境变量的核心配置文件，用于集中管理 API Key、数据库连接等敏感信息。

然后，将刚才复制的 API Key 填入 .env 文件中的 TAVILY_API_KEY 对应项中。填写完成后请及时保存文件，确保配置生效。

配置2、firecrawl API-KEY：开启网络爬虫功能

接下来，需要获取网页爬虫服务 Firecrawl 的 API Key。请前往 Firecrawl 官方网站（ Firecrawl），完成账号注册。注册成功后，在用户控制台（Dashboard）页面中即可复制专属的 API Key，用于后续配置。

然后同样是在.env文件中写入FIRECRAWL_API_KEY。

配置3、Daytona：开启沙盒环境功能

接下来是配置沙盒环境工具 Daytona。由于 Daytona 的设置相对复杂，建议结合文字版课件操作，便于复制和参考。

首先，访问 Daytona 官方网站（Daytona - Secure Infrastructure for Running AI-Generated Code）并完成注册流程。

完成注册后，我们需要为 Suna 创建一个专属镜像，以确保 Daytona 能够正常运行项目代码。在左侧菜单栏点击 “Image（镜像）” 选项，接着点击右上角的 “Create Image（创建镜像）” 按钮。

在弹出的创建窗口中，填写预设的 Image Name 和 Entrypoint 信息，然后点击创建。该过程配置较多，建议直接参考课件中的具体参数，复制粘贴以减少出错。

Image name: kortix/suna:0.1.2
Entrypoint: /usr/bin/supervisord -n -c /etc/supervisor/conf.d/supervisord.conf

随后，耐心等待镜像导入和构建过程完成。完成后，该镜像即可用于 Suna 项目的沙盒环境运行，无需其他额外配置。

接下来，点击菜单中的 “Keys” 选项，进入 API Key 管理页面。点击 “Create API Key（创建 API 密钥）” 按钮，生成一个新的 API Key，用于在 Suna 项目中连接和调用 Daytona 服务。创建完成后请妥善保存该密钥，以便后续配置使用。

最后，将刚刚生成的 Daytona API Key 填入 .env 配置文件中的对应字段中，确保格式正确并保存文件。至此，Daytona 沙盒环境的配置就已完成，Suna 智能体具备了安全的远程代码执行能力。

配置4、supabase：开启完整后端支持

接下来是配置后端服务工具 Supabase。首先，访问 Supabase 官方网站（Supabase | The Postgres Development Platform.），并根据页面引导完成账户注册和项目创建流程。

创建项目时，你可以自定义项目名称，例如此处我们创建了一个名为 test 的项目。项目创建成功后，Supabase 将为该项目自动生成数据库实例及相关服务接口，用于支撑 Suna 项目的数据存储、用户管理和权限控制等功能。

然后，在 Supabase 项目主页左侧菜单中选择 “Project Settings”，接着点击 “Data API” 选项。向下滚动页面，找到 “schemas” 配置区域，确认已选中如图所示的三种模式（schemas）。确保这三种格式被正确勾选，以保证数据库接口的正常使用和数据访问权限的配置。

接着，在当前页面向上滚动，找到页面顶部显示的三项核心信息（如图所示）。请分别复制这三项内容，并填入 .env 文件中对应的三个变量位置，确保信息准确无误。完成后保存配置文件，以便 Suna 项目能够正确连接 Supabase 后端服务。

然后保存.env文件并退出。

接下来回到后端文件夹的命令行中，输入如下三项命令，第一条命令是是登陆supabase，输入后会自动弹出确认登陆的网页；

npx supabase login npx supabase link --project-ref <your-project-ref> npx supabase db push

如果需要输入验证码，从自动打开的网页里面复制。

输入账号密码即可。第二条link命令是在本地设置默认项目，需要关联到supabase对应的项目ID；

而第三条push命令则是将本地数据表格式同步到关联的项目中。

全部执行完后，Suna后端配置全部完成。

最终env文件

四、配置Suna底层大模型

最后一个阶段是设置 Suna 的基础模型配置。强烈建议分别为 Suna 的前端和后端配置不同的大模型，这样可以显著提升系统的响应速度和整体性能。

后端大模型配置： 推荐使用 Claude 3.7 模型，该模型目前在 Agent 能力方面表现最为出色，也是 Suna 默认采用的后端模型。您可以通过官方渠道（例如某宝购买或自行注册）获取 Claude 的 API Key，然后将该密钥填写到后端配置文件 .env 中对应的字段，完成配置。
前端大模型配置： 建议配置 DeepSeek 模型，专门优化前端交互体验，保证响应的流畅与精准。

这样区分配置，能够让 Suna 在不同任务场景下发挥最佳效能。

此外，您也可以填写 OpenRouter 的 API Key，以便调用包括 DeepSeek 模型在内的多种主流大模型，提升灵活性和模型选择范围。

接下来，使用文本编辑器打开前端的配置文件 .env.local，进行相应的 API Key 填写和配置调整。

然后，按照示例截图所示，将部分后端配置内容复制并粘贴到前端的配置文件中。最后，在文件的末尾找到 OPENAI_API_KEY 一栏，填写 DeepSeek 官方提供的 API Key。至此，前端的全部配置便完成了。

然后，记得保存并关闭配置文件。

至此，所有准备工作已经完成，接下来即可按照以下步骤启动 Suna 项目：

第一步：借助docker启动Redis
第二步：启动Suna后端
第三步：启动Suna前端

首先需要借助docker启动Redis。我们需要确保之前安装的docker已经启动，然后在后端文件夹中打开命令行，输入Redis启动命令。

docker compose up redis

然后同样在后端文件夹中再打开一个命令行，输入如下命令开启Suna的后端服务。

cd /Users/dcs/study/Suna修改后项目源码/suna/backend python api.py

最后，在前端文件夹中打开命令行，输入如下命令开启Suna前端。

cd /Users/dcs/study/Suna修改后项目源码/suna/frontend npm run dev # 注意：如果提示没权限/suna/frontend/node_modules/.bin/next: Permission denied， # 请赋予权限 chmod +x /Users/dcs/study/Suna修改后项目源码/suna/frontend/node_modules/.bin/next

前端启动后，打开本地浏览器，访问 http://localhost:3000，即可进入 Suna 界面进行使用。首次使用时，系统会提示您进行注册，只需填写任意有效邮箱完成注册流程，即可开始体验全部功能。

然后，完成注册后即可登录到对话页面，开始与 Suna 进行交互。Suna 不仅支持普通的聊天对话，还能够执行各种复杂任务。当前你看到的，就是一个完整的复杂任务执行流程示例：

Suna 会先对任务进行整体规划，
然后按照计划一步步执行各项操作，
在执行过程中，Suna 能够调用命令行命令、操作浏览器、编写和运行 Python 代码，
甚至能在沙盒环境中创建、编辑相关文件，完成复杂的自动化工作。

这种高度灵活且强大的能力，使得 Suna 不仅是聊天助手，更是一个多功能的智能执行平台。

五、功能介绍

简单来说，Suna 是一款全能型 AI 助手，能够通过自然语言对话帮助你完成各种实际任务。它不仅仅是一个聊天机器人，更是一个能真正解决问题、自动化工作流程的数字伙伴。

最令人兴奋的是，Suna 完全开源，任何人都可以自由使用、学习和二次开发，推动智能助手技术的普及与进步。

Git地址: https://github.com/kortix-ai/suna

Suna 的四大核心组件

后端 API

基于 Python 和 FastAPI 构建，负责处理 RESTful 接口请求、线程管理，

并通过 LiteLLM 集成 OpenAI、Anthropic 及其他大型语言模型（LLM），为智能体提供强大的语言理解和生成能力。
前端

使用 Next.js 和 React 技术打造，提供响应式的用户界面，

包括流畅的聊天窗口、管理仪表盘等，确保用户体验友好顺畅。
Agent Docker

为每个智能代理提供独立隔离的执行环境，支持浏览器自动化操作、代码解释执行、文件系统访问、各种工具集成及安全控制，确保任务执行高效且安全。
Supabase 数据库

负责数据的持久化管理，包括用户认证、权限控制、对话历史记录、文件存储、代理状态监控、数据分析及实时订阅推送，构建可靠的数据基础设施。