OpenViking

简体中文

English

简体中文

English

外观

检索 ​

OpenViking 提供两种搜索方法：find 用于简单的语义搜索，search 用于带会话上下文的复杂检索。

find 与 search 对比 ​

方面findsearch
意图分析否是
会话上下文否是
查询扩展否是
默认限制数1010
使用场景简单查询对话式搜索

API 参考 ​

find() ​

基本向量相似度搜索。

参数

参数类型必填默认值说明
querystr是-搜索查询字符串
target_uristr否""限制搜索范围到指定的 URI 前缀
limitint否10最大返回结果数
node_limitint否None可选 HTTP 别名；如果提供，会覆盖 limit
score_thresholdfloat否None最低相关性分数阈值
filterDict否None元数据过滤器
sincestr否None时间下界，支持 2h 或 ISO 8601 / YYYY-MM-DD。不带时区的值按 UTC 解释。CLI --after 会映射到这个字段
untilstr否None时间上界，支持 30m 或 ISO 8601 / YYYY-MM-DD。不带时区的值按 UTC 解释。CLI --before 会映射到这个字段
time_field"updated_at" 或 "created_at"否"updated_at"since / until 使用的元数据时间字段
include_provenancebool否False在序列化结果中附带 provenance / query-plan 细节
telemetrybool 或 object否False在响应中附带遥测数据

FindResult 结构

python
class FindResult:
    memories: List[MatchedContext]   # 记忆上下文
    resources: List[MatchedContext]  # 资源上下文
    skills: List[MatchedContext]     # 技能上下文
    query_plan: Optional[QueryPlan]  # 查询计划（仅 search）
    query_results: Optional[List[QueryResult]]  # 详细结果
    total: int                       # 总数（自动计算）

MatchedContext 结构

python
class MatchedContext:
    uri: str                         # Viking URI
    context_type: ContextType        # "resource"、"memory" 或 "skill"
    is_leaf: bool                    # 是否为叶子节点
    abstract: str                    # L0 内容
    category: str                    # 分类
    score: float                     # 相关性分数 (0-1)
    match_reason: str                # 匹配原因
    relations: List[RelatedContext]  # 关联上下文

Python SDK (Embedded / HTTP)

python
results = client.find("how to authenticate users")

recent_emails = client.find(
    "invoice",
    target_uri="viking://resources/email/",
    since="7d",
    time_field="created_at",
)

for ctx in results.resources:
    print(f"URI: {ctx.uri}")
    print(f"Score: {ctx.score:.3f}")
    print(f"Type: {ctx.context_type}")
    print(f"Abstract: {ctx.abstract[:100]}...")
    print("---")

HTTP API

POST /api/v1/search/find
bash
curl -X POST http://localhost:1933/api/v1/search/find \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your-key" \
  -d '{
    "query": "how to authenticate users",
    "limit": 10
  }'

CLI

bash
openviking find "how to authenticate users" [--uri viking://resources/] [--limit 10]
openviking find "invoice" --after 7d

--after 会映射为 API since，--before 会映射为 API until。

响应

json
{
  "status": "ok",
  "result": {
    "memories": [],
    "resources": [
      {
        "uri": "viking://resources/docs/auth/",
        "context_type": "resource",
        "is_leaf": false,
        "abstract": "Authentication guide covering OAuth 2.0...",
        "score": 0.92,
        "match_reason": "Semantic match on authentication"
      }
    ],
    "skills": [],
    "total": 1
  },
  "time": 0.1
}

示例：使用 Target URI 搜索

Python SDK (Embedded / HTTP)

python
# 仅在资源中搜索
results = client.find(
    "authentication",
    target_uri="viking://resources/"
)

# 仅在用户记忆中搜索
results = client.find(
    "preferences",
    target_uri="viking://user/memories/"
)

# 仅在技能中搜索
results = client.find(
    "web search",
    target_uri="viking://agent/skills/"
)

# 在特定项目中搜索
results = client.find(
    "API endpoints",
    target_uri="viking://resources/my-project/"
)

HTTP API

bash
# 仅在资源中搜索
curl -X POST http://localhost:1933/api/v1/search/find \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your-key" \
  -d '{
    "query": "authentication",
    "target_uri": "viking://resources/"
  }'

# 使用分数阈值搜索
curl -X POST http://localhost:1933/api/v1/search/find \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your-key" \
  -d '{
    "query": "API endpoints",
    "target_uri": "viking://resources/my-project/",
    "score_threshold": 0.5,
    "limit": 5
  }'

带会话上下文和意图分析的搜索。

参数

参数类型必填默认值说明
querystr是-搜索查询字符串
target_uristr否""限制搜索范围到指定的 URI 前缀
sessionSession否None用于上下文感知搜索的会话（SDK）
session_idstr否None用于上下文感知搜索的会话 ID（HTTP）
limitint否10最大返回结果数
node_limitint否None可选 HTTP 别名；如果提供，会覆盖 limit
score_thresholdfloat否None最低相关性分数阈值
filterDict否None元数据过滤器
sincestr否None时间下界，支持 2h 或 ISO 8601 / YYYY-MM-DD。不带时区的值按 UTC 解释。CLI --after 会映射到这个字段
untilstr否None时间上界，支持 30m 或 ISO 8601 / YYYY-MM-DD。不带时区的值按 UTC 解释。CLI --before 会映射到这个字段
time_field"updated_at" 或 "created_at"否"updated_at"since / until 使用的元数据时间字段
include_provenancebool否False在序列化结果中附带 provenance / query-plan 细节
telemetrybool 或 object否False在响应中附带遥测数据

Python SDK (Embedded / HTTP)

python
from openviking.message import TextPart

# 创建带对话上下文的会话
session = client.session()
session.add_message("user", [
    TextPart(text="I'm building a login page with OAuth")
])
session.add_message("assistant", [
    TextPart(text="I can help you with OAuth implementation.")
])

# 搜索能够理解对话上下文
results = client.search(
    "best practices",
    session=session,
    since="2h"
)

for ctx in results.resources:
    print(f"Found: {ctx.uri}")
    print(f"Abstract: {ctx.abstract[:200]}...")

HTTP API

POST /api/v1/search/search
bash
curl -X POST http://localhost:1933/api/v1/search/search \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your-key" \
  -d '{
    "query": "best practices",
    "session_id": "abc123",
    "since": "2h",
    "time_field": "updated_at",
    "limit": 10
  }'

CLI

bash
openviking search "best practices" [--session-id abc123] [--limit 10]
openviking search "watch vs scheduled" --after 2026-03-15 --before 2026-03-15

--after 会映射为 API since，--before 会映射为 API until。

响应

json
{
  "status": "ok",
  "result": {
    "memories": [],
    "resources": [
      {
        "uri": "viking://resources/docs/oauth-best-practices/",
        "context_type": "resource",
        "is_leaf": false,
        "abstract": "OAuth 2.0 best practices for login pages...",
        "score": 0.95,
        "match_reason": "Context-aware match: OAuth login best practices"
      }
    ],
    "skills": [],
    "query_plan": {
      "expanded_queries": ["OAuth 2.0 best practices", "login page security"]
    },
    "total": 1
  },
  "time": 0.1
}

示例：不使用会话的搜索

Python SDK (Embedded / HTTP)

python
# search 也可以在没有会话的情况下使用
# 它仍然会对查询进行意图分析
results = client.search(
    "how to implement OAuth 2.0 authorization code flow",
)

for ctx in results.resources:
    print(f"Found: {ctx.uri} (score: {ctx.score:.3f})")

HTTP API

bash
curl -X POST http://localhost:1933/api/v1/search/search \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your-key" \
  -d '{
    "query": "how to implement OAuth 2.0 authorization code flow"
  }'

grep() ​

通过模式（正则表达式）搜索内容。

参数

参数类型必填默认值说明
uristr是-要搜索的 Viking URI
patternstr是-搜索模式（正则表达式）
case_insensitivebool否False忽略大小写
node_limitint否None最大搜索节点数
exclude_uristr否None要排除在搜索之外的 URI 前缀
level_limitint否5最大目录遍历深度

Python SDK (Embedded / HTTP)

python
results = client.grep(
    "viking://resources/",
    "authentication",
    case_insensitive=True
)

print(f"Found {results['count']} matches")
for match in results['matches']:
    print(f"  {match['uri']}:{match['line']}")
    print(f"    {match['content']}")

HTTP API

POST /api/v1/search/grep
bash
curl -X POST http://localhost:1933/api/v1/search/grep \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your-key" \
  -d '{
    "uri": "viking://resources/",
    "pattern": "authentication",
    "case_insensitive": true
  }'

CLI

bash
openviking grep viking://resources/ "authentication" [--ignore-case]

响应

json
{
  "status": "ok",
  "result": {
    "matches": [
      {
        "uri": "viking://resources/docs/auth.md",
        "line": 15,
        "content": "User authentication is handled by..."
      }
    ],
    "count": 1
  },
  "time": 0.1
}

glob() ​

通过 glob 模式匹配文件。

参数

参数类型必填默认值说明
patternstr是-Glob 模式（例如 **/*.md）
uristr否"viking://"起始 URI
node_limitint否None最大返回匹配数

Python SDK (Embedded / HTTP)

python
# 查找所有 markdown 文件
results = client.glob("**/*.md", "viking://resources/")
print(f"Found {results['count']} markdown files:")
for uri in results['matches']:
    print(f"  {uri}")

# 查找所有 Python 文件
results = client.glob("**/*.py", "viking://resources/")
print(f"Found {results['count']} Python files")

HTTP API

POST /api/v1/search/glob
bash
curl -X POST http://localhost:1933/api/v1/search/glob \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your-key" \
  -d '{
    "pattern": "**/*.md",
    "uri": "viking://resources/"
  }'

CLI

bash
openviking glob "**/*.md" [--uri viking://resources/]

响应

json
{
  "status": "ok",
  "result": {
    "matches": [
      "viking://resources/docs/api.md",
      "viking://resources/docs/guide.md"
    ],
    "count": 2
  },
  "time": 0.1
}

检索流程 ​

查询 -> 意图分析 -> 向量搜索 (L0) -> 重排序 (L1) -> 结果
  1. 意图分析（仅 search）：理解查询意图，扩展查询
  2. 向量搜索：使用 Embedding 查找候选项
  3. 重排序：使用内容重新评分以提高准确性
  4. 结果：返回 top-k 上下文

处理结果 ​

渐进式读取内容 ​

Python SDK (Embedded / HTTP)

python
results = client.find("authentication")

for ctx in results.resources:
    # 从 L0（摘要）开始 - 已包含在 ctx.abstract 中
    print(f"Abstract: {ctx.abstract}")

    if not ctx.is_leaf:
        # 获取 L1（概览）
        overview = client.overview(ctx.uri)
        print(f"Overview: {overview[:500]}...")
    else:
        # 加载 L2（内容）
        content = client.read(ctx.uri)
        print(f"File content: {content}")

HTTP API

bash
# 步骤 1：搜索
curl -X POST http://localhost:1933/api/v1/search/find \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your-key" \
  -d '{"query": "authentication"}'

# 步骤 2：读取目录结果的概览
curl -X GET "http://localhost:1933/api/v1/content/overview?uri=viking://resources/docs/auth/" \
  -H "X-API-Key: your-key"

# 步骤 3：读取文件结果的完整内容
curl -X GET "http://localhost:1933/api/v1/content/read?uri=viking://resources/docs/auth.md" \
  -H "X-API-Key: your-key"

获取关联资源 ​

Python SDK (Embedded / HTTP)

python
results = client.find("OAuth implementation")

for ctx in results.resources:
    print(f"Found: {ctx.uri}")

    # 获取关联资源
    relations = client.relations(ctx.uri)
    for rel in relations:
        print(f"  Related: {rel['uri']} - {rel['reason']}")

HTTP API

bash
# 获取资源的关联关系
curl -X GET "http://localhost:1933/api/v1/relations?uri=viking://resources/docs/auth/" \
  -H "X-API-Key: your-key"

最佳实践 ​

使用具体的查询 ​

python
# 好 - 具体的查询
results = client.find("OAuth 2.0 authorization code flow implementation")

# 效果较差 - 过于宽泛
results = client.find("auth")

限定搜索范围 ​

python
# 在相关范围内搜索以获得更好的结果
results = client.find(
    "error handling",
    target_uri="viking://resources/my-project/"
)

在对话中使用会话上下文 ​

python
# 对于对话式搜索，使用会话
from openviking.message import TextPart

session = client.session()
session.add_message("user", [
    TextPart(text="I'm building a login page")
])

# 搜索能够理解上下文
results = client.search("best practices", session=session)

相关文档 ​

Released under the Apache-2.0 License.

Copyright OpenViking contributors