02-先学会怎么用

先学会怎么用 OpenViking

最简单的学习入口

最值得先看的示例：

• examples/quick_start.py

这个例子非常重要，因为它告诉你： 作者希望你怎么使用 OpenViking。

quick_start 在做什么

示例代码大致是这样一条流程：

1. 创建客户端
2. 初始化存储和索引
3. 加资源（URL / 文件 / 目录）
4. 浏览资源树
5. 读取内容
6. 等待语义处理完成
7. 获取摘要和概览
8. 做语义检索

用小白的话翻译这段流程

第 1 步：创建客户端

client = ov.OpenViking(path="./data")

意思是：

在本地创建一个 OpenViking 数据空间，存在 ./data 里。

这里 OpenViking 实际上默认映射到同步客户端 SyncOpenViking。

第 2 步：初始化

client.initialize()

意思是：

把底层存储、索引等准备好。

第 3 步：加入资源

client.add_resource(path="...")

意思是：

把一个 URL、文件或者目录送进 OpenViking，让它变成可管理的上下文资源。

第 4 步：看目录结构

client.ls(root_uri)

意思是：

像看文件系统一样看资源树。

第 5 步：读内容

client.read(uri)

意思是：

读取某个资源内容。

第 6 步：等待语义处理

client.wait_processed()

意思是：

等后台把语义索引、摘要等处理完成。

第 7 步：获取抽象和概览

client.abstract(root_uri)
client.overview(root_uri)

意思是：

让系统告诉你“这个资源大概讲什么”。

第 8 步：检索

client.find("what is openviking", target_uri=root_uri)

意思是：

在目标资源树里按语义查找相关内容。

小白应该先记住的 API

• initialize()：初始化
• add_resource()：导入资源
• ls()：看目录
• read()：读文件
• abstract()：看摘要
• overview()：看概览
• find()：快速语义检索
• search()：更复杂的检索

本地模式 vs HTTP 模式

示例里还有一句注释：

# client = ov.SyncHTTPClient(url="http://localhost:1933")

这说明 OpenViking 至少支持两种使用方式：

1. Embedded / Local 模式

ov.OpenViking(path="./data")

特点：

• 嵌入式
• 直接在本地进程里用
• 适合单机实验、快速开发

2. HTTP 模式

ov.SyncHTTPClient(url="http://localhost:1933")

特点：

• 连到独立服务端
• 更像客户端/服务端架构
• 适合部署后远程访问

小白一句话理解

你可以先把 OpenViking 想成：

一个能把外部资源“收进来、整理好、做语义处理、再查出来”的 Agent 上下文仓库。