初学者快速入门指南 🚀

这是一份为初学者设计的详细指南，将引导你完成 Youtu-agent 框架的设置和使用。即使你是 AI 智能体开发的新手，也能成功运行 Youtu-agent。

📖 先决条件

开始之前，请确保你的系统满足以下要求：

• Python 3.12 或更高版本。
• Git 工具。
• UV 包管理器：一个极快的 Python 包和项目管理器。我们将在下面的设置步骤中安装它。
• API 密钥：你需要为你智能体将使用的底层 LLM 获取 API 密钥（例如，DeepSeek、OpenAI 等）——这是必需的。可选地，你还可以获取 Serper 和 Jina 的 API 密钥以增强功能。
  • DeepSeek API Key：访问 DeepSeek 或 腾讯云 并注册帐户以获取 API 密钥。
  • Serper API Key（可选）：访问 Serper 并获取 API 密钥。
  • Jina API Key（可选）：访问 Jina 并获取 API 密钥。

---

🔧 详细安装步骤

步骤 1：克隆项目代码

打开终端（命令行）并执行以下命令：

# 在本地克隆项目
git clone https://github.com/TencentCloudADP/youtu-agent.git

# 进入项目目录
cd youtu-agent

初学者提示： 如果你看到 git: command not found，这意味着 Git 未安装。请先安装 Git。

步骤 2：安装 UV 包管理器

你可以使用以下命令安装 UV（参考 UV 官方仓库的 安装指南）：

# 在 Linux/macOS 上安装 UV
curl -LsSf https://astral.sh/uv/install.sh | sh

# 在 Windows 上
powershell -c "irm https://astral.sh/uv/install.ps1 | iex"

或者简单地使用 pip：

pip install uv

# 或者 pipx
pipx install uv

验证安装：

uv --version

如果显示版本号，则安装成功。

步骤 3：创建并激活虚拟环境

# 创建虚拟环境
uv venv

# 激活虚拟环境
# Linux/macOS:
source .venv/bin/activate

# Windows:
# .venv\Scripts\activate

初学者提示： 激活虚拟环境后，你将在命令行提示符前看到 (Youtu-agent) 标识符，如下所示：

# Linux/macOS
(Youtu-agent) your-username:~/path/to/youtu-agent$

# Windows
# (Youtu-agent) path\to\Youtu-agent>

步骤 4：安装项目依赖

# 安装所有依赖，包括开发工具
uv sync --group dev

步骤 5：配置环境变量

# 复制环境变量模板文件
cp .env.example .env

现在你需要编辑 .env 文件并添加你的 API 密钥：

# 使用文本编辑器打开配置文件
# 你可以使用 nano、vim 或任何你喜欢的编辑器
nano .env

在打开的文件中，找到以下行并填入你的 API 密钥：

# LLM 配置 - **必需**
# 我们以 DeepSeek 为例 LLM 提供商。
UTU_LLM_TYPE=chat.completions
UTU_LLM_MODEL=deepseek-chat
UTU_LLM_BASE_URL=https://api.deepseek.com/v1
UTU_LLM_API_KEY=[DeepSeek_API_key]
# 或使用腾讯云上的 DeepSeek 等效版本
# UTU_LLM_TYPE=chat.completions
# UTU_LLM_MODEL=deepseek-v3
# UTU_LLM_BASE_URL=https://api.lkeap.cloud.tencent.com/v1
# UTU_LLM_API_KEY=[DeepSeek_API_key]

# 工具配置 - 可选
SERPER_API_KEY=[Serper_API_key]
JINA_API_KEY=[Jina_API_key]

更高级的配置在后面的 高级设置 部分和 配置文档 中提供。

重要提醒： - 将 [DeepSeek_API_key] 替换为你的实际 DeepSeek API 密钥 - 如果你还没有 Serper 和 Jina API 密钥，可以留空，但某些功能可能无法工作

---

🎯 首次运行测试

让我们验证安装是否成功：

测试 1：运行简单搜索智能体

# 运行具有搜索功能的简单智能体作为启动测试
# python scripts/cli_chat.py --help
python scripts/cli_chat.py --config_name simple/search_agent.yaml

如果一切正常，你应该看到：

__   __            _                                      _   
\ \ / / ___  _  _ | |_  _  _  ___  __ _  __ _  ___  _ _  | |_ 
 \ V / / _ \| || ||  _|| || ||___|/ _` |/ _` |/ -_)| ' \ |  _|
  |_|  \___/ \_,_| \__| \_,_|     \__,_|\__, |\___||_||_| \__|
                                        |___/                 

----------------------------------------------------------------------------------------------------
Usage: python cli_chat.py --config_name <config_name>
Quit: exit, quit, q
----------------------------------------------------------------------------------------------------
>

现在你可以尝试问一些问题：

> 你能做什么？

初学者提示： - 输入 quit、exit 或 q 退出对话 - 如果遇到错误，请检查你的 UV 环境是否已激活且 UTU_LLM_* API 密钥是否配置正确

测试 2：运行管弦乐队示例

通过指定其配置文件运行多智能体（计划 - 执行）管弦乐队智能体：

# 运行 SVG 生成器示例
python examples/svg_generator/main.py

这将启动一个可以在你的终端（命令行）上生成 SVG 图形代码的智能体。

你也可以为智能体运行一个 Web UI：

python examples/svg_generator/main_web.py

更多详情请参见 前端。

---

运行评估

该框架包含一个强大的评估工具来对智能体性能进行基准测试。

运行完整实验

此命令运行从智能体部署到判断的完整评估。

python scripts/run_eval.py --config_name <your_eval_config> --exp_id <your_exp_id> --dataset WebWalkerQA --concurrency 5

重新判断现有结果

如果你已经运行了部署阶段，只想重新运行判断阶段，请使用此脚本：

python scripts/run_eval.py --config_name <your_eval_config> --exp_id <your_exp_id> --dataset WebWalkerQA --step judge

导出实验数据

你也可以从数据库中导出特定实验的轨迹和结果：

python scripts/db/dump_db.py --exp_id "<your_exp_id>"

---

🔧 高级设置

一旦你熟悉了基础知识，你可能希望进一步自定义你的设置：

数据库配置

评估框架使用 SQL 数据库（默认为 SQLite）来存储数据集和实验结果。默认的 SQLite 数据库 (sqlite:///test.db) 非常适合入门，但你可以为生产使用其他数据库。

要使用不同的数据库（例如 PostgreSQL），请在 .env 文件中设置 UTU_DB_URL 环境变量：

# 对于 PostgreSQL
UTU_DB_URL="postgresql://user:password@host:port/database"

# 对于 MySQL
UTU_DB_URL="mysql://user:password@host:port/database"

# 默认 SQLite（推荐初学者使用）
UTU_DB_URL="sqlite:///test.db"

初学者提示： 除非你对不同的数据库系统有特定要求，否则坚持使用 SQLite。

跟踪

我们使用 Phoenix 作为默认的跟踪服务来观察智能体行为。这有助于你逐步了解你的智能体在做什么。

要启用跟踪，请将这些环境变量添加到你的 .env 文件中：

# Phoenix 跟踪配置
PHOENIX_ENDPOINT=[Phoenix_endpoint]
PHOENIX_BASE_URL=[Phoenix_base_url]
PHOENIX_PROJECT_NAME=[Phoenix_project_name]

该框架还支持与 openai-agents 库兼容的任何跟踪服务。更多选项请参见 官方跟踪处理器列表。

初学者提示： 跟踪是可选的，但对调试和理解你的智能体行为非常有帮助。你可以最初跳过它，并在想要深入了解时再添加。

使用不同的 LLM 提供商

虽然我们的示例使用 DeepSeek，你可以通过修改你的 .env 文件轻松切换到其他 LLM 提供商：

# 对于 OpenAI GPT 模型
UTU_LLM_TYPE=chat.completions
UTU_LLM_MODEL=gpt-4
UTU_LLM_BASE_URL=https://api.openai.com/v1
UTU_LLM_API_KEY=[Openai_API_key]

# 对于 Anthropic Claude（通过 OpenAI 兼容 API）
UTU_LLM_TYPE=chat.completions
UTU_LLM_MODEL=claude-3-sonnet-20240229
UTU_LLM_BASE_URL=[Anthropic_compatible_endpoint]
UTU_LLM_API_KEY=[Anthropic_API_key]

初学者提示： 从一个 LLM 提供商开始，在尝试其他提供商之前先熟悉框架。

---

🎨 创建你的第一个自定义智能体

现在你已经成功运行了项目，让我们创建你自己的智能体！

步骤 1：创建配置文件

# 创建一个新的智能体配置文件
mkdir -p configs/agents/my_agents

创建文件 configs/agents/my_agents/my_first_agent.yaml：

# @package _global_
defaults:
  - /model/base@model.   # 加载基础 LLM 模型设置
  - /tools/search@toolkits.search.  # 加载内置 'search' 工具包
  - _self_   # 加载当前配置文件，允许覆盖

agent:
    name: MyFirstAgent
    instructions: "你是一个可以搜索网络的有用助手。"

步骤 2：编写并运行 Python 脚本

import asyncio
from utu.agents import SimpleAgent

async def main():
    # 使用你的自定义智能体配置
    async with SimpleAgent(config="my_agents/my_first_agent.yaml") as agent:
        # 提出问题
        await agent.chat("今天北京的天气怎么样？")

asyncio.run(main())

步骤 3：测试功能

尝试在脚本中问一些其他问题，例如： - "你好，请介绍一下你自己" - "请搜索最新的科技新闻" - "帮我分析人工智能的发展趋势"

---

📚 下一步

恭喜！你已成功运行 Youtu-agent。接下来，你可以：

1. 学习配置： 阅读完整的 配置文档 以了解如何自定义智能体并理解所有可用的配置选项
2. 添加工具： 阅读 工具文档 以了解如何向智能体添加新功能
3. 探索更多示例： 查看 示例 中的各种示例以获取更多详细用例和高级脚本
4. 深入了解评估： 通过阅读 评估框架文档 了解更多关于评估框架的工作原理。

---

🆘 获取帮助

如果你在使用项目时遇到问题，你可以：

1. 查看 完整文档
2. 在 GitHub Issues 中提问
3. 查看项目的 示例代码

祝你编码愉快！🎉