Merge branch 'main' into feat/mem0

Author: cuericlee

.gitignore

@@ -167,6 +167,13 @@ cython_debug/
 #  option (not recommended) you can uncomment the following to ignore the entire idea folder.
 .idea/
 
+# Visual Studio Code
+#  Visual Studio Code specific template is maintained in a separate VisualStudioCode.gitignore
+#  that can be found at https://github.com/github/gitignore/blob/main/Global/VisualStudioCode.gitignore
+#  and can be added to the global gitignore or merged into this file. However, if you prefer,
+#  you could uncomment the following to ignore the entire vscode folder
+.vscode/
+
 # Ruff stuff:
 .ruff_cache/
 

README.md

@@ -15,6 +15,17 @@ A [tutorial](https://github.com/volcengine/veadk-python/blob/main/veadk_tutorial
 
 ## Installation
 
+### From PyPI
+
+```python
+pip install veadk-python
+
+# install extensions
+pip install veadk-python[extensions]
+```
+
+### Build from source
+
 We use `uv` to build this project ([how-to-install-uv](https://docs.astral.sh/uv/getting-started/installation/)).
 
 ```bash

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

@@ -24,3 +24,12 @@ navigation:
 
 1. **卡在 release 阶段**
    - 请先在 VeFaaS 平台开通权限。
+
+   - ![开通权限](/images/troubleshooting-01.png)
+
+   - 新账号开通后，缺少ServerlessApplicationRole授权
+      - 前往火山引擎函数服务官网，进入创建应用页面（例如[这里](https://console.volcengine.com/vefaas/region:vefaas+cn-beijing/application/create?templateId=67f7b4678af5a6000850556c)）点击「一键授权」即可
+      - ![角色授权](/images/troubleshooting-02.png)
+
+2. **安装依赖失败，显示依赖安装空间不足**
+   - VeFaaS 最大依赖安装大小默认为 250 MB，若需更大空间，请联系 VeFaaS 产品团队扩容。

docs/content/7.knowledgebase/1.knowledgebase.md

@@ -5,12 +5,24 @@ navigation:
   icon: i-lucide-database
 ---
 
-VeADK 支持将结构化或文档型知识作为 Agent 的外部知识源接入。开发者可选择自建知识库，或使用火山引擎现有知识库。自建知识库与使用火山引擎现有知识库的最大区别是：知识文档的分片和数据库维护。VeADK 中知识库的创建如下：
+## 概述
+
+VeADK 基于 Llama-index 作为知识库的主要处理入口。开发者可上传文本、文件、目录，我们会为您进行自动切片。
+
+创建知识库时，您必须要提供您的 `app_name`（将会用来自动构建索引名称），或指定一个知识库的索引：
 
 ```python
-from veadk.knowledgebase.knowledgebase import KnowledgeBase
+from veadk.knowledgebase import KnowledgeBase
+
+# 通过指定 `app_name`
+knowledgebase = KnowledgeBase(
+    backend="local", app_name="my_app_name"
+)
 
-knowledgebase = KnowledgeBase(backend=...)
+# 通过指定 `index`
+knowledgebase = KnowledgeBase(
+    backend="local", index="my_index"
+)
 ```
 
 知识库中的 backend 字段定义如下：
@@ -23,39 +35,90 @@ knowledgebase = KnowledgeBase(backend=...)
 | redis | Redis 数据库，但不具备向量搜索功能 |
 | mysql | MySQL 数据库，但不具备向量搜索功能 |
 
-## 自建知识库
+## 使用知识库
 
-自建知识库需要开发者本地进行知识文档的切片，并维护一个数据库（或云数据库）来存储知识文档。
+以下示例通过建设一个智能客服 Agent，来说明知识库的能力：
 
-以下示例通过使用 opensearch 定义一个如下的自建知识库：
+::code-tree{default-value="agent.py"}
 
-```python
-from veadk import Agent
-from veadk.knowledgebase.knowledgebase import KnowledgeBase
+```markdown[qa.md]
+# 智能客服知识库
+
+## 1. 公司简介
+
+VE科技是一家专注于智能客服与知识管理的高科技公司。我们的核心产品是 **智能客服系统**，通过自然语言处理与知识库检索，为企业客户提供高效、智能的自动化客服解决方案。
+
+---
+
+## 2. 产品功能说明
+
+- **自动问答**：基于知识库，快速响应常见问题。  
+- **多渠道接入**：支持网页、App、微信、飞书等渠道。  
+- **智能推荐**：根据上下文推荐相关答案。  
+- **数据分析**：提供用户问题统计与客服绩效报告。  
+- **自助知识库管理**：支持非技术人员快速编辑知识内容。  
+
+---
+
+## 3. 常见问题 (FAQ)
+
+### Q1: 智能客服系统支持哪些语言？
 
-knowledgebase = KnowledgeBase(backend="opensearch")
-knowledgebase.add(
-    knowledgebase_data, app_name=app_name, user_id=user_id, session_id=session_id
-) # knowledgebase_data 应当是已切片完成的格式，定义为`list[str]`
+A1: 目前支持 **中文** 和 **英文**，后续将逐步增加日语、韩语等多语言支持。  
 
-# 将知识库挂载至Agent
-agent = Agent(knowledgebase=knowledgebase)
+### Q2: 系统可以接入现有的 CRM 吗？
+
+A2: 可以。我们的系统支持通过 API 与主流 CRM 系统（如 Salesforce、Zoho、金蝶）进行无缝集成。  
+
+### Q3: 如果机器人无法回答用户问题，会怎么办？
+
+A3: 系统会自动将问题转接至人工客服，并在后台记录该问题，方便管理员补充到知识库。  
+
+### Q4: 知识库内容多久更新一次？
+
+A4: 知识库支持 **实时更新**，管理员提交后即可立即生效。  
+
+---
+
+## 4. 联系我们
+
+- 官网：[https://www.example.com](https://www.example.com)  
+- 客服邮箱：support@ve
+- 服务热线：400-123-4567  
 ```
 
-## 火山知识库
+```python[agent.py]
+import asyncio
 
-VeADK 中提供了火山引擎支持的知识库 [VikingDB](https://www.volcengine.com/docs/84313/1254437)，支持用户直接上传本地文档，文档切片和存储维护均在云上自动执行：
+from veadk import Agent, Runner
+from veadk.knowledgebase import KnowledgeBase
+from veadk.memory import ShortTermMemory
 
-```python
-from veadk import Agent
-from veadk.knowledgebase.knowledgebase import KnowledgeBase
+app_name = "app"
+user_id = "user"
+session_id = "session"
 
-FILE_PATH = ...
+knowledgebase = KnowledgeBase(backend="local", app_name=app_name)
+knowledgebase.add_from_files(files=["./qa.md"])
+
+agent = Agent(
+    name="customer_service",
+    instruction="Answer customer's questions according to your knowledgebase.",
+    knowledgebase=knowledgebase,
+)
 
-knowledgebase = KnowledgeBase(backend="viking")
-knowledgebase.add(
-    FILE_PATH, app_name=app_name, user_id=user_id, session_id=session_id
+runner = Runner(
+    agent=agent,
+    short_term_memory=ShortTermMemory(),
+    app_name=app_name,
+    user_id=user_id,
 )
 
-agent = Agent(knowledgebase=knowledgebase)
+response = asyncio.run(
+    runner.run(messages="你们的产品叫什么？都有什么功能？", session_id=session_id)
+)
+
+print(response)
 ```
+
+::