nao

第一开源分析智能体

🌐 官网 · 📚 文档 · 💬 Slack

nao 是什么？

nao 是一个用于构建和部署分析智能体的框架。
使用 nao-core CLI 创建你的分析智能体上下文：数据、元数据、建模、规则等。
部署一个用户友好的聊天界面，让任何人都可以与你的智能体互动，并对你的数据进行分析。

核心功能

面向数据团队：

• 🧱 开放的上下文构建器 — 为你的智能体创建类似文件系统的上下文。在上下文中添加任何内容：数据、元数据、文档、工具、MCP 等，没有任何限制。
• 🏳️ 数据栈无关 — 适用于任何数据仓库、技术栈、上下文类型以及大语言模型。
• 🕵🏻‍♀️ 智能体可靠性与透明度 — 在将智能体部署给用户之前，先对其进行单元测试以评估其性能。对上下文进行版本管理，并跟踪智能体随时间的性能表现。收集用户反馈以改进智能体，并追踪其使用情况。
• 🔒 自托管且安全 — 自行托管你的分析智能体，并使用你自己的大语言模型密钥，以确保数据的最大安全性。

面向业务用户：

• 🤖 自然语言转洞察 — 用简单的英语提问，即可立即获得分析结果。
• 📊 原生数据可视化 — 直接在聊天界面中创建和自定义可视化图表。
• 🧊 透明的推理过程 — 清晰地查看智能体的推理逻辑及数据来源。
• 👍 便捷的反馈机制 — 当回答正确或错误时，可直接向数据团队发送反馈。

⚡️ 一分钟快速启动你的智能体

• 步骤 1：安装 nao-core 包

  pip install nao-core
  

• 步骤 2：初始化一个 nao 项目

  nao init
  

  系统会提示你：

  • 为项目命名
  • 是否连接数据库（可选）
  • 是否在智能体上下文中添加代码库（可选）
  • 添加大语言模型密钥（可选）
  • 是否设置 Slack 连接（可选）

  💡 你可以跳过任何可选问题，并在后续的 nao_config.yaml 文件中进行配置。

  此操作将创建：

  • 一个以项目名称命名的新文件夹
  • 用于存放上下文文件的目录结构
  • 一个 nao_config.yaml 配置文件
  • 一个 RULES.md 文件

• 步骤 3：验证你的设置

  进入项目文件夹并运行：

  nao debug
  

• 步骤 4：同步上下文

  nao sync
  

  这将把你的上下文文件（数据、元数据、代码库等）填充到上下文文件夹中。

• 步骤 5：启动聊天界面并提问

  nao chat
  

  这将启动 nao 聊天界面。聊天窗口将在浏览器中打开，地址为 http://localhost:5005。从此处，你可以开始向你的智能体提问。

评估框架

在将智能体部署给用户之前，先对其进行单元测试。首先，在 tests/ 文件夹中创建包含问题和预期 SQL 查询的 YAML 文件。然后，使用 nao test 命令测量智能体在这些示例上的表现：

nao test

通过以下命令查看测试结果：

nao test server

命令列表

nao --help
用法：nao COMMAND

╭─ 命令 ────────────────────────────────────────────────────────────────╮
│ chat         启动 nao 聊天界面。                                       │
│ init         初始化一个新的 nao 项目。                                │
│ sync         从你的上下文源（数据库、代码库）同步上下文          │
│ test         测量智能体在测试样例中的性能。                        │
│ debug        调试和排查你的 nao 设置问题。                           │
│ --help (-h)  显示此消息并退出。                                     │
│ --version    显示应用程序版本。                                     │
╰───────────────────────────────────────────────────────────────────────────╯

🐳 Docker

从 DockerHub 拉取镜像：

docker pull getnao/nao:latest

使用镜像中自带的示例项目，通过 Docker 运行 nao 聊天界面：

docker run -d \
  --name nao \
  -p 5005:5005 \
  -e BETTER_AUTH_URL=http://localhost:5005 \
  getnao/nao:latest

或者，使用你本地的 nao 项目通过 Docker 运行 nao 聊天界面：

docker run -d \
  --name nao \
  -p 5005:5005 \
  -e BETTER_AUTH_URL=http://localhost:5005 \
  -v /path/to/your/nao-project:/app/project \
  -e NAO_DEFAULT_PROJECT_PATH=/app/project \
  getnao/nao:latest

访问 UI：http://localhost:5005（或你所配置的任何 URL）。

更多详细信息请参阅 DockerHub 页面。

如需端到端自托管部署（例如在 Cloud Run 上搭配 PostgreSQL），请参考 部署指南。

👩🏻‍💻 开发

开发环境搭建、常用命令及贡献指南，请参阅 CONTRIBUTING.md。

📒 技术栈

后端

• Fastify: https://fastify.dev/docs/latest/
• Drizzle: https://orm.drizzle.team/docs/get-started
• tRPC 路由器: https://trpc.io/docs/server/routers

前端

• tRPC 客户端: https://trpc.io/docs/client/tanstack-react-query/usage
• Tanstack Query: https://tanstack.com/query/latest/docs/framework/react/overview
• Shadcn: https://ui.shadcn.com/docs/components

⛹️‍♀️ 加入社区

• 给本仓库点个 Star
• 订阅发布通知（Watch → Custom → Releases）
• 关注我们的 LinkedIn
• 加入我们的 Slack
• 参与仓库贡献！

🫰🏻 合作伙伴

nao Labs 是 Y Combinator 的优秀成员！

📄 许可证

本项目采用 Apache 2.0 许可证授权——详情请参阅 LICENSE 文件。

nao 快速上手指南

nao 是一个开源的分析智能体（Analytics Agent）框架，允许数据团队构建上下文并部署聊天界面，让业务用户通过自然语言直接查询数据、生成可视化图表。

环境准备

在开始之前，请确保您的开发环境满足以下要求：

• 操作系统：Linux, macOS 或 Windows (WSL 推荐)
• Python：版本 3.8 或更高
• 包管理器：pip (通常随 Python 安装)
• 可选依赖：
  • 若需容器化部署，需安装 Docker。
  • 若需连接数据库，请确保网络可访问对应的数据仓库。

💡 国内加速建议：如果 pip install 速度较慢，建议使用国内镜像源（如清华源或阿里源）进行安装。

安装步骤

方式一：使用 pip 安装（推荐）

直接使用 pip 安装核心包 nao-core。

使用默认源：

pip install nao-core

使用国内镜像源（推荐国内用户）：

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

方式二：使用 Docker

如果您希望跳过环境配置直接运行，可以使用 Docker 镜像。

docker pull getnao/nao:latest

基本使用

以下是从零开始构建并运行一个本地分析智能体的最小化流程。

1. 初始化项目

在项目目录下运行初始化命令。该命令会引导您创建项目结构、配置文件及规则文件。

nao init

执行过程中会根据提示输入：

• 项目名称
• 是否连接数据库（可选）
• 是否添加代码仓库到上下文（可选）
• 是否配置 LLM API Key（可选，可稍后在 nao_config.yaml 中配置）
• 是否配置 Slack 连接（可选）

💡 所有可选配置均可在后续通过编辑生成的 nao_config.yaml 文件完成。

2. 验证与同步上下文

进入生成的项目文件夹，首先运行调试命令检查配置是否正确：

nao debug

确认无误后，同步数据源、元数据等到本地上下文文件夹：

nao sync

3. 启动聊天界面

运行以下命令启动本地 Web 服务：

nao chat

命令执行后，浏览器将自动打开或在终端显示访问地址（默认为 http://localhost:5005）。您可以在界面中输入自然语言问题（例如：“上个季度的销售额是多少？”），nao 将自动解析意图、生成 SQL 并返回数据分析结果或可视化图表。

---

附：常用命令速查

命令	说明
nao init	初始化新项目
nao sync	从数据源同步上下文
nao chat	启动聊天 UI 界面
nao debug	诊断当前配置问题
nao test	运行单元测试评估智能体性能