Skip to content

Commit 311a4b0

Browse files
yaozheng-fangyaozheng-fang
authored
feat(docs): refine docs (#169)
* feat(docs): refine docs * change base url
1 parent 5368a2b commit 311a4b0

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

70 files changed

+18357
-4509
lines changed

‎.github/workflows/deploy-docs.yaml‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -36,12 +36,12 @@ jobs:
3636
- name: Build documentation
3737
run: |
3838
cd docs
39-
npm run docs:build
39+
npx nuxt generate --extends docus
4040
4141
- name: Upload artifact for GitHub Pages
4242
uses: actions/upload-pages-artifact@v3
4343
with:
44-
path: docs/docs/.vuepress/dist
44+
path: docs/.output/public/
4545

4646
- name: Deploy to GitHub Pages
4747
id: deploy

‎.gitignore‎

Lines changed: 5 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -185,4 +185,8 @@ cython_debug/
185185
**/node_modules/
186186

187187
# 忽略所有 .temp 目录
188-
**/.temp/
188+
**/.temp/
189+
190+
**/.nuxt
191+
**/.data
192+
**./output

‎docs/content/1.introduction/.navigation.yml‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,2 @@
1+
title: 介绍
2+
icon: false

docs/docs/introduction.md renamed to docs/content/1.introduction/1.overview.md

Lines changed: 43 additions & 63 deletions
Original file line numberDiff line numberDiff line change
@@ -1,39 +1,25 @@
1-
# 介绍
1+
---
2+
title: VeADK
3+
description: 欢迎使用火山引擎智能体框架 VeADK
4+
navigation:
5+
icon: i-lucide-house
6+
seo:
7+
title: Introduction
8+
description: Discover how to create, manage, and publish documentation
9+
effortlessly with Docus.
10+
---
211

3-
## 关于VeADK
12+
欢迎使用火山引擎智能体框架 **VeADK（Volcengine Agent Development Kit）**，是由[火山引擎](https://www.volcengine.com/)推出的为 Agent 智能体的应用构建提供开发、部署、观测、评测等全流程云原生解决方案。
413

5-
**VeADK（Volcengine Agent Development Kit）** 是由[火山引擎](https://www.volcengine.com/)推出的一套面向智能体（Agent）开发的全流程框架，旨在为开发者提供一套面向智能体构建、云端部署、评测与优化的全流程开发框架。
14+
相较于现有的智能体开发框架，具备与火山引擎产品体系深度融合的优势，帮助开发者更高效地构建企业级 AI 智能体应用。
615

7-
VeADK 相较于现有的智能体开发框架，具备与火山引擎产品体系深度融合的优势，帮助开发者更高效地构建企业级 AI 智能体应用。
16+
## 特性
817

9-
VeADK 各组件与火山引擎相关产品的结合矩阵：
18+
- **生态兼容**：与 Google ADK 完全兼容
19+
- **快速部署**：本地项目部署到云端的时延在分钟级别，并提供镜像部署、代码部署等多种部署形式
20+
- **一证通行**：基于火山引擎AK/SK进行企业级统一密钥管理
1021

11-
| **组件** | **火山引擎产品** | **说明** |
12-
| :-- | :-- | :-- |
13-
| 大模型 | [火山方舟](https://www.volcengine.com/product/ark) | 提供各类语言模型、多模态模型的推理服务 |
14-
| 提示词工程 | [PromptPilot](https://promptpilot.volcengine.com/) | 提供提示词管理、优化能力 |
15-
| 工具 | [火山方舟大模型生态广场](https://www.volcengine.com/mcp-marketplace) | 提供各类 MCP Server |
16-
| | [Web search](https://www.volcengine.com/docs/85508/1650263) | 提供公域数据搜索功能 |
17-
| | [VeSearch](https://www.volcengine.com/docs/85508/1512748) | 提供信息搜索与云端自动整合功能 |
18-
| | [Web Scraper](https://www.volcengine.com/docs/84296/1545470) | 定制化内容查询（邀测） |
19-
| | 飞书 Lark | 进行飞书相关操作 |
20-
| | [AI 数据湖服务 LAS](https://www.volcengine.com/product/las) | 提供数据湖内的海量数据存储与查询能力 |
21-
| 短期记忆 | [Viking 记忆库](https://www.volcengine.com/docs/84313/1783345) | 提供记忆存储、优化、摘要等功能 |
22-
| | [火山引擎云数据库 MySQL 版](https://www.volcengine.com/product/rds-mysql) | 记忆存储 |
23-
| 长期记忆 | [Viking DB](https://www.volcengine.com/docs/84313/1254437) | 记忆向量化存储和检索 |
24-
| | [云搜索服务](https://www.volcengine.com/product/es)（OpenSearch） | 记忆向量化存储和检索 |
25-
| 知识库 | [Viking DB](https://www.volcengine.com/docs/84313/1254437) | 知识向量化存储和检索 |
26-
| | [云搜索服务](https://www.volcengine.com/product/es)（OpenSearch） | 知识向量化存储和检索 |
27-
| 可观测 | [应用性能监控全链路版](https://www.volcengine.com/product/apmplus)（APMPlus） | 调用链路观测 |
28-
| | [扣子罗盘](https://www.coze.cn/loop) （Coze Loop） | 调用链路观测 |
29-
| | [日志服务](https://www.volcengine.com/product/tls) | 调用链路观测、日志存储与检索 |
30-
| 评测 | [扣子罗盘](https://www.coze.cn/loop) （Coze Loop） | 在线评测 |
31-
| 云部署 | [火山引擎函数服务](https://www.volcengine.com/product/vefaas) （VeFaaS） | 提供一键上云能力 |
32-
| | [火山引擎 API 网关](https://www.volcengine.com/product/apig) | 提供鉴权、路由等能力 |
33-
| | [火山引擎持续交付](https://www.volcengine.com/product/cp) | 提供用户仓库向 VeFaaS 进行基于镜像的持续交付部署 |
34-
| | [火山引擎镜像仓库](https://www.volcengine.com/product/cr) | 提供用户代码镜像托管维护 |
35-
36-
## VeADK 核心优势
22+
## 核心能力
3723

3824
### 更快速的企业级部署
3925

@@ -70,37 +56,31 @@ VeADK 各组件与火山引擎相关产品的结合矩阵：
7056
- 提供贴近实际工业场景的各类开发和部署用例，涵盖数据库访问、数据湖读写、复杂任务编排等多样场景。
7157
- 提供可直接复用的代码模板与配置示例，帮助开发者快速上手并解决实际业务问题。
7258

73-
## 社区支持
74-
75-
您可以扫描下方二维码，加入 VeADK 讨论群组：
76-
77-
<p align="center">
78-
<img src="/images/veadk_group_qrcode.jpg" alt="VeADK 讨论组二维码" width="400" />
79-
</p>
80-
81-
## 整体方案
82-
83-
在 VeADK 中，智能体的构建与生命周期的管理围绕`Agent`，`Runner`等核心组件进行：
84-
85-
### Agent
59+
## 火山引擎生态
8660

87-
`Agent`是智能体的主体，基于大模型处理用户输入，调用不同的组件及各类工具，最终返回给用户结果。
88-
89-
### Runner
90-
91-
`Runner`是智能体的执行器，负责智能体运行时的生命周期管理。
92-
93-
在多租场景下，`Runner`通过三个属性来确定资源空间：
94-
95-
- `app_name`：应用名称
96-
- `user_id`：用户ID
97-
- `session_id`：某个用户某次会话的ID
98-
99-
VeADK 的组件会利用这三个属性来构建某些数据的索引，例如知识库组件将会根据`app_name`与`user_id`来进行空间数据的索引，实现多租场景下数据空间的安全隔离。
100-
101-
## Milestone
61+
VeADK 各组件与火山引擎相关产品的结合矩阵：
10262

103-
| 时间节点 | 事件 |
104-
| --- | --- |
105-
| 2025/08/01 | V0.1.0 版本发布 |
106-
| 2025/08/14 | V0.2.1 版本发布 |
63+
| **组件** | **火山引擎产品** | **说明** |
64+
| :-- | :-- | :-- |
65+
| 大模型 | [火山方舟](https://www.volcengine.com/product/ark) | 提供各类语言模型、多模态模型的推理服务 |
66+
| 提示词工程 | [PromptPilot](https://promptpilot.volcengine.com/) | 提供提示词管理、优化能力 |
67+
| 工具 | [火山方舟大模型生态广场](https://www.volcengine.com/mcp-marketplace) | 提供各类 MCP Server |
68+
| | [Web search](https://www.volcengine.com/docs/85508/1650263) | 提供公域数据搜索功能 |
69+
| | [VeSearch](https://www.volcengine.com/docs/85508/1512748) | 提供信息搜索与云端自动整合功能 |
70+
| | [Web Scraper](https://www.volcengine.com/docs/84296/1545470) | 定制化内容查询（邀测） |
71+
| | 飞书 Lark | 进行飞书相关操作 |
72+
| | [AI 数据湖服务 LAS](https://www.volcengine.com/product/las) | 提供数据湖内的海量数据存储与查询能力 |
73+
| 短期记忆 | [Viking 记忆库](https://www.volcengine.com/docs/84313/1783345) | 提供记忆存储、优化、摘要等功能 |
74+
| | [火山引擎云数据库 MySQL 版](https://www.volcengine.com/product/rds-mysql) | 记忆存储 |
75+
| 长期记忆 | [Viking DB](https://www.volcengine.com/docs/84313/1254437) | 记忆向量化存储和检索 |
76+
| | [云搜索服务](https://www.volcengine.com/product/es)（OpenSearch） | 记忆向量化存储和检索 |
77+
| 知识库 | [Viking DB](https://www.volcengine.com/docs/84313/1254437) | 知识向量化存储和检索 |
78+
| | [云搜索服务](https://www.volcengine.com/product/es)（OpenSearch） | 知识向量化存储和检索 |
79+
| 可观测 | [应用性能监控全链路版](https://www.volcengine.com/product/apmplus)（APMPlus） | 调用链路观测 |
80+
| | [扣子罗盘](https://www.coze.cn/loop) （Coze Loop） | 调用链路观测 |
81+
| | [日志服务](https://www.volcengine.com/product/tls) | 调用链路观测、日志存储与检索 |
82+
| 评测 | [扣子罗盘](https://www.coze.cn/loop) （Coze Loop） | 在线评测 |
83+
| 云部署 | [火山引擎函数服务](https://www.volcengine.com/product/vefaas) （VeFaaS） | 提供一键上云能力 |
84+
| | [火山引擎 API 网关](https://www.volcengine.com/product/apig) | 提供鉴权、路由等能力 |
85+
| | [火山引擎持续交付](https://www.volcengine.com/product/cp) | 提供用户仓库向 VeFaaS 进行基于镜像的持续交付部署 |
86+
| | [火山引擎镜像仓库](https://www.volcengine.com/product/cr) | 提供用户代码镜像托管维护 |

‎docs/content/1.introduction/2.installation.md‎

Lines changed: 116 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,116 @@
1+
---
2+
title: 安装
3+
description: VeADK安装方式
4+
navigation:
5+
icon: i-lucide-download
6+
---
7+
8+
## 从 PyPI 安装
9+
10+
您可以直接使用 Python 包管理工具 `pip` 从 [PyPI 平台](https://pypi.org/project/veadk-python/) 来安装 `veadk-python`：
11+
12+
:::code-group
13+
14+
```bash [最新稳定版]
15+
pip install veadk-python
16+
```
17+
18+
```bash [指定版本]
19+
pip install veadk-python==0.2.7
20+
```
21+
22+
:::
23+
24+
<!-- 如果您使用知识库、长期记忆等进阶功能，请进一步安装 `veadk-python` 中的扩展包：
25+
26+
```bash [Terminal]
27+
pip install veadk-python[extensions]
28+
``` -->
29+
30+
## 从源码构建
31+
32+
::steps
33+
34+
### 下载源码至本地
35+
36+
将VeADK的代码包从Github下载到本地：
37+
38+
```bash [Terminal]
39+
git clone https://github.com/volcengine/veadk-python.git
40+
41+
cd veadk-python
42+
```
43+
44+
### 配置 `uv` 环境
45+
46+
本项目使用 `uv` 进行构建，了解如何（[安装 `uv`](https://docs.astral.sh/uv/getting-started/installation/)）。
47+
48+
创建 `uv` 虚拟环境：
49+
50+
```bash [Terminal]
51+
# 选择 3.10 及以上版本
52+
uv venv --python 3.10
53+
```
54+
55+
激活 `uv` 虚拟环境：
56+
57+
:::code-group
58+
59+
```bash [Linux]
60+
source .venv/bin/activate
61+
```
62+
63+
```bash [MacOS]
64+
source .venv/bin/activate
65+
```
66+
67+
```bash [Windows CMD]
68+
.venv\Scripts\activate.bat
69+
```
70+
71+
```bash [Windows PowerShell]
72+
.venv\Scripts\Activate.ps1
73+
```
74+
75+
:::
76+
77+
### 安装 VeADK
78+
79+
```bash [Terminal]
80+
uv pip install .
81+
82+
# 或以本地可编辑模式安装
83+
# uv pip install -e .
84+
```
85+
86+
::
87+
88+
## 贡献代码
89+
90+
我们接受对`veadk-python`的能力扩展或 BUG 修复贡献，请按照以下方式进行代码贡献：
91+
92+
::steps
93+
94+
### 从源码构建、安装
95+
96+
请参考[这里](#从源码构建)。
97+
98+
### 开发
99+
100+
依照开发规范文档进行开发（即将上线）。
101+
102+
### 安装 `pre-commit`
103+
104+
`pre-commit` 将在您提交代码前进行一系列检查，例如代码格式规范检查、密钥泄漏检查等。未使用 `pre-commit` 检查过的提交将不会通过 Github 中的 CI/CD 工作流检查，这意味着代码将不会被合并。
105+
106+
```bash [Terminal]
107+
pip install pre-commit
108+
109+
pre-commit install .
110+
```
111+
112+
### 等待代码审查
113+
114+
您提交的代码贡献将会在 1 至 2 个工作日内被处理。
115+
116+
::

‎docs/content/1.introduction/3.quickstart.md‎

Lines changed: 37 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,37 @@
1+
---
2+
title: 快速开始
3+
description: 构建您的第一个智能体
4+
navigation:
5+
icon: i-lucide-rocket
6+
---
7+
8+
我们提供了一个供您完整体验 VeADK 核心功能的[教程](https://github.com/volcengine/veadk-python/blob/main/veadk_tutorial.ipynb)（基于 Jupyter Notebook），或者您也可以直接在 [Google Colab](https://colab.research.google.com/github/volcengine/veadk-python/blob/main/veadk_tutorial.ipynb) 中打开。
9+
10+
通过 VeADK，您可以构建一个简易智能体：
11+
12+
::steps
13+
14+
### Agent 文件
15+
16+
```python [agent.py]
17+
import asyncio
18+
19+
from veadk import Agent
20+
21+
agent = Agent()
22+
asyncio.run(agent.run("Hello world!"))
23+
```
24+
25+
### 执行
26+
27+
您需要通过环境变量方式，来设置能够调用大模型的 API Key 或者其它身份验证信息。
28+
29+
```bash [Terminal]
30+
# 通过 API Key
31+
MODEL_AGENT_API_KEY=... python agent.py
32+
33+
# 通过火山引擎 AK/SK
34+
VOLCENGINE_ACCESS_KEY=... VOLCENGINE_SECRET_KEY=... python agent.py
35+
```
36+
37+
::

‎docs/content/1.introduction/4.troubleshooting.md‎

Lines changed: 26 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,26 @@
1+
---
2+
title: Troubleshooting
3+
description: 安装、运行以及使用中的各类常见问题汇总
4+
navigation:
5+
icon: i-lucide-wrench
6+
---
7+
8+
## 安装
9+
10+
1. **使用知识库时，提示未找到 `llama-index` 等包**
11+
- 请使用 `pip install veadk-python[extensions]` 安装扩展包。
12+
13+
## 配置
14+
15+
1. **设置火山引擎 AK/SK 后，提示获取模型 API Key 失败**
16+
- VeADK 不会帮助您自动创建火山引擎方舟平台 API Key，请先在平台创建。
17+
18+
## 使用
19+
20+
1. **是否兼容 Google ADK**
21+
- 是
22+
23+
## 部署
24+
25+
1. **卡在 release 阶段**
26+
- 请先在 VeFaaS 平台开通权限。

‎docs/content/2.configurations/.navigation.yml‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
title: 配置

‎docs/content/2.configurations/1.system.md‎

Lines changed: 34 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,34 @@
1+
---
2+
title: 配置管理系统
3+
description: 实现自动身份管理、云上资源设施管理等
4+
navigation:
5+
icon: i-lucide-heading-1
6+
---
7+
8+
VeADK 内置了一套配置管理系统，您能够通过定义一个 `config.yaml` 文件来管理您的各项配置。文件中的配置项将会在运行时被自动加载为对应的环境变量。
9+
10+
为管理配置项，VeADK 提供了根据 `config.yaml` 文件的自动化配置管理方案。您在配置文件中的所有配置将会根据层级，自动转为大写并使用下划线连接，统一注册成为运行时的环境变量。
11+
12+
例如下面的配置项：
13+
14+
```yaml [config.yaml]
15+
model:
16+
name:
17+
api_key:
18+
api_base:
19+
base_a:
20+
base_b:
21+
...
22+
```
23+
24+
将会被转为如下几条环境变量：
25+
26+
```bash
27+
MODEL_NAME=
28+
MODEL_API_KEY=
29+
MODEL_API_BASE_BASE_A=
30+
MODEL_API_BASE_BASE_B=
31+
...
32+
```
33+
34+
VeADK 中提供了 `getenv` 方法来读取相关配置，您无需在各组件中次手动传入某个配置的参数。

0 commit comments

Comments
 (0)