Moss Agent 技能

能力

Moss 是面向对话式 AI 的实时语义搜索运行时。它提供低于 10 毫秒的查找延迟与即时索引更新能力，可在浏览器、终端设备或云端运行——无论您的 agent 部署在何处。Agent 可自主创建索引、嵌入文档、执行语义/混合搜索，并管理文档生命周期，无需运维基础设施。平台自动处理嵌入生成、索引持久化及可选的云同步，使 agent 能专注于检索逻辑，而非底层设施。

技能

索引管理

• 创建索引：使用文档与嵌入模型选择构建新的语义索引
• 加载索引：从持久化存储中加载已有索引以供查询
• 获取索引：检索指定索引的元数据（如文档数量、模型类型等）
• 列出索引：枚举项目下的全部索引
• 删除索引：移除索引及其所有关联数据

文档操作

• 添加文档：向已有索引插入或更新（upsert）文档，并支持可选元数据
• 获取文档：按 ID 检索已存储文档，或获取全部文档
• 删除文档：根据 ID 从索引中移除特定文档

搜索与检索

• 语义搜索：使用自然语言进行查询，基于向量相似度匹配
• 关键词搜索：采用 BM25 算法进行关键词精确匹配
• 混合搜索：融合语义与关键词搜索，支持通过 alpha 参数配置权重（Python SDK）
• 元数据过滤：按文档元数据（如 category、language、tags）约束检索结果
• Top-K 结果：返回指定数量的最佳匹配文档及其相关性得分

嵌入模型

• moss-minilm：轻量快速模型，专为边缘端/离线场景优化（默认）
• moss-mediumlm：更高精度模型，在对准确性要求严苛的场景中保持合理性能

SDK 方法

API 动作

所有 REST API 操作均通过 POST /v1/manage（基础 URL：https://service.usemoss.dev/v1）发起，请求体中需包含 action 字段：

工作流

基础语义搜索工作流

1. 使用项目凭据初始化 MossClient
2. 调用 createIndex() 并传入文档与模型选项（JavaScript 中为 { modelId: 'moss-minilm' }；Python 中为字符串 "moss-minilm"）
3. 调用 loadIndex() 以准备索引用于查询
4. 调用 query() 并传入搜索文本及 topK（JavaScript）或 QueryOptions(top_k=...)（Python）
5. 处理返回的带得分的文档结果

混合搜索工作流（Python）

Python SDK 中通过 QueryOptions 提供 alpha 加权混合功能：

1. 按上述方式创建并加载索引
2. 调用 query() 时传入含 alpha 参数的 QueryOptions 对象
3. alpha=1.0 表示纯语义搜索，alpha=0.0 表示纯关键词搜索，alpha=0.6 表示 60/40 混合
4. 默认偏向语义搜索，适用于对话式场景

文档更新工作流

1. 初始化 client 并确保索引已存在
2. 调用 addDocs() 传入新文档（默认为 upsert —— 相同 ID 的文档将被更新）
3. 调用 deleteDocs() 按 ID 删除过时文档

语音 Agent 上下文注入工作流

此为语音 Agent 流水线的可选集成模式，并非本技能的自动行为。

1. 在 Agent 启动时初始化 MossClient 并加载索引
2. 在应用代码中，对每个用户消息调用 query() 以检索相关上下文
3. 在 LLM 生成响应前，将搜索结果注入其上下文
4. 以知识增强的方式响应（无工具调用延迟）

离线优先搜索工作流

1. 使用本地嵌入模型与文档创建索引
2. 从本地存储加载索引
3. 查询完全在设备端执行，延迟低于 10 毫秒
4. 可选地同步至云端以实现备份与共享

集成

语音 Agent 框架

• LiveKit：通过 inferedge-moss SDK 将上下文注入语音 Agent 流水线
• Pipecat：通过 pipecat-moss 包提供流水线处理器，自动注入检索结果

上下文

认证

SDK 需要项目凭据：

• MOSS_PROJECT_ID：来自 Moss Portal 的项目标识符
• MOSS_PROJECT_KEY：来自 Moss Portal 的项目访问密钥

export MOSS_PROJECT_ID=your_project_id
export MOSS_PROJECT_KEY=your_project_key

REST API 要求每次请求包含以下内容：

• x-project-key 请求头：项目访问密钥
• x-service-version: v1 请求头：API 版本
• JSON 请求体中的 projectId 字段

curl -X POST "https://service.usemoss.dev/v1/manage" 
  -H "Content-Type: application/json" 
  -H "x-service-version: v1" 
  -H "x-project-key: moss_access_key_xxxxx" 
  -d '{"action": "listIndexes", "projectId": "project_123"}'

包安装

文档结构

interface DocumentInfo {
  id: string;        // 必填：唯一标识符
  text: string;      // 必填：待嵌入与检索的内容
  metadata?: object; // 可选：用于过滤的键值对
}

查询参数

模型选择

性能预期

• 本地查询延迟低于 10 毫秒（依赖硬件）
• 索引更新即时生效，无需全量重建语料库
• 同步为可选功能；计算保留在设备端
• 无需管理任何基础设施

分块最佳实践

• 每块建议约 200–500 个 token
• 块间重叠 10–20%，以保留上下文连贯性
• 标准化空白字符并清除模板内容（boilerplate）

常见错误

异步模式

所有 SDK 方法均为异步 —— 务必始终使用 await：

// JavaScript
import { MossClient, DocumentInfo } from '@inferedge/moss'
const client = new MossClient(process.env.MOSS_PROJECT_ID!, process.env.MOSS_PROJECT_KEY!)
await client.createIndex('faqs', docs, { modelId: 'moss-minilm' })
await client.loadIndex('faqs')
const results = await client.query('faqs', 'search text', { topK: 5 })

# Python
import os
from inferedge_moss import MossClient, QueryOptions
client = MossClient(os.getenv('MOSS_PROJECT_ID'), os.getenv('MOSS_PROJECT_KEY'))
await client.create_index('faqs', docs, 'moss-minilm')
await client.load_index('faqs')
results = await client.query('faqs', 'search text', QueryOptions(top_k=5, alpha=0.6))

更多文档与导航，请参阅：https://docs.moss.dev/llms.txt