VikingDB Node.js SDK (Vector + Knowledge)

该 SDK 覆盖 VikingDB 的两类能力：

• vector: Viking 向量库（Collection / Index / Search / Embedding / Rerank）
• knowledge: Viking 知识库（Collection / Doc & Point CRUD / Search / Rerank / Chat / ServiceChat）

Node.js 版本要求：>=18。

安装

npm i @volcengine/vikingdb-sdk

导入方式

推荐按模块导入（类型更清晰）：

import * as vector from '@volcengine/vikingdb-sdk/vector'
import * as knowledge from '@volcengine/vikingdb-sdk/knowledge'

也支持从根包导入（CommonJS），根包会把 vector 的导出铺平，并额外挂载 vector/knowledge 两个命名空间：

import vikingdb = require('@volcengine/vikingdb-sdk')

// vikingdb.createClient = vector.createClient
const vc = vikingdb.createClient(vikingdb.AuthIAM('ak', 'sk'))
const kc = vikingdb.knowledge.createClient(vikingdb.knowledge.AuthIAM('ak', 'sk'))

鉴权与配置

Vector 鉴权

vector 支持 4 种鉴权：

• AuthIAM(accessKey, secretKey)
• AuthAPIKey(apiKey)：会设置 Authorization: Bearer <apiKey>
• AuthHeader(headers)：自定义 Header
• AuthNone()

Knowledge 鉴权

knowledge 支持：

• AuthIAM(accessKey, secretKey)
• AuthAPIKey(apiKey)
• AuthNone()

ClientConfig 默认值

vector.defaultConfig()：

• endpoint: https://api-vikingdb.vikingdb.cn-beijing.volces.com
• region: cn-beijing
• timeoutMs: 30000
• maxRetries: 3
• service: vikingdb

knowledge.defaultConfig()：

• endpoint: https://api-knowledgebase.mlp.cn-beijing.volces.com
• region: cn-beijing
• timeoutMs: 30000
• maxRetries: 3
• service: air

你可以通过 createClient(auth, config) 覆盖 endpoint/region/timeoutMs/maxRetries/userAgent/service。

Vector 快速开始

1. 创建 Client 与 IndexClient

import * as vector from '@volcengine/vikingdb-sdk/vector'

const client = vector.createClient(
  vector.AuthIAM(process.env.VIKINGDB_AK || '', process.env.VIKINGDB_SK || ''),
  {
    endpoint: process.env.VIKINGDB_ENDPOINT, // 可选
    region: process.env.VIKINGDB_REGION, // 可选
  },
)

const indexClient = client.index({
  collection_name: process.env.VIKINGDB_COLLECTION || '',
  index_name: process.env.VIKINGDB_INDEX || '',
  project_name: process.env.VIKINGDB_PROJECT_NAME, // 可选
  resource_id: process.env.VIKINGDB_RESOURCE_ID, // 可选
})
if (!indexClient) throw new Error('failed to init index client')

2. 执行一次 Search（示例：Random）

const resp = await indexClient.searchByRandom({ limit: 1 })
console.log('request_id=', resp?.request_id, 'hits=', resp?.result?.data?.length ?? 0)

3. Collection 数据写入与读取（Upsert / Update / Fetch / Delete）

const collectionClient = client.collection({
  collection_name: process.env.VIKINGDB_COLLECTION || '',
  project_name: process.env.VIKINGDB_PROJECT_NAME,
  resource_id: process.env.VIKINGDB_RESOURCE_ID,
})
if (!collectionClient) throw new Error('failed to init collection client')

// 写入：注意 id 字段在接口层是 unknown，业务上建议使用 string 承接 int64 id，避免 JS number 精度问题
await collectionClient.upsert({
  data: [
    {
      title: 'Lifecycle quickstart',
      paragraph: Date.now() % 1_000_000,
      score: 42.5,
      text: 'Simple lifecycle payload written inline for the reference flow.',
    },
  ],
})

// 检索 -> 得到 id 后再更新/读取/删除
const s = await indexClient.searchByMultiModal({
  text: 'Need the lifecycle quickstart chapter overview',
  need_instruction: false,
  limit: 1,
  output_fields: ['title', 'score'],
})
const id = s?.result?.data?.[0]?.id
if (id == null) throw new Error('missing id')

await collectionClient.update({
  data: [
    {
      __AUTO_ID__: id,
      text: 'Updated lifecycle payload for reference clarity.',
      score: 47.0,
    } as Record<string, unknown>,
  ],
})

const f = await collectionClient.fetch({ ids: [id] })
console.log('fetch=', f?.result?.fetch?.[0])

await collectionClient.delete({ ids: [id] })

Knowledge 快速开始

1. 创建 Client 与 CollectionClient

import * as knowledge from '@volcengine/vikingdb-sdk/knowledge'

const client = knowledge.createClient(
  knowledge.AuthIAM(process.env.VOLC_AK || '', process.env.VOLC_SK || ''),
)

const collection = client.collection({
  resource_id: process.env.VIKING_COLLECTION_RID || '',
  collection_name: process.env.VIKING_COLLECTION_NAME || 'financial_reports',
  project: process.env.VIKING_PROJECT || 'default',
})
if (!collection) throw new Error('failed to init collection client')

2. Doc CRUD（AddDocV2 / GetDoc / UpdateDocMeta / ListDocs）

import * as knowledge from '@volcengine/vikingdb-sdk/knowledge'

const docId = 'google-report-2025-q1'
const tagList: knowledge.MetaItem[] = [
  { field_name: 'category', field_type: 'string', field_value: 'financial_report' },
  { field_name: 'quarter', field_type: 'string', field_value: 'Q1' },
  { field_name: 'year', field_type: 'int64', field_value: 2025 },
]

await collection.addDocV2({
  doc_id: docId,
  doc_name: 'Google 2025 Q1 Financial Report',
  doc_type: 'pdf',
  uri: 'https://pdf.dfcfw.com/pdf/H3_AP202504281663850212_1.pdf',
  tag_list: tagList,
})

const info = await collection.getDoc(docId, true)
console.log('get_doc=', info)

await collection.updateDocMeta(docId, [
  ...tagList,
  { field_name: 'updated_at', field_type: 'int64', field_value: 1714560000 },
])

const list = await collection.listDocs({ offset: 0, limit: 10, return_token_usage: true })
console.log('list_docs=', list)

3. Point CRUD（AddPoint / GetPoint / UpdatePoint / ListPoints / DeletePoint）

const add = await collection.addPoint({
  doc_id: docId,
  chunk_type: 'text',
  chunk_title: 'Revenue Highlights',
  content: 'Revenue grew 12% YoY to $3.4B.',
  fields: [
    { field_name: 'topic', field_type: 'string', field_value: 'revenue' },
    { field_name: 'year', field_type: 'int64', field_value: 2025 },
    { field_name: 'quarter', field_type: 'string', field_value: 'Q1' },
  ],
})

const pointId = add.data?.point_id
if (!pointId) throw new Error('missing point_id')

await collection.updatePoint(pointId, { content: 'Updated.' })
const point = await collection.getPoint(pointId, true)
console.log('get_point=', point)

const points = await collection.listPoints({ offset: 0, limit: 10, get_attachment_link: true })
console.log('list_points=', points)

await collection.deletePoint({ point_id: pointId })

4. Search + Chat（ChatCompletion / Stream / ServiceChat）

// 检索
const sk = await collection.searchKnowledge({ query: '2025 Q1 revenue growth', limit: 10, dense_weight: 0.5 })
console.log('search_knowledge=', sk)

// 直接模型对话（可选 api_key）
const chatResp = await client.chatCompletion({
  model: 'Doubao-1-5-pro-32k',
  messages: [{ role: 'user', content: '总结下 2025 Q1 财报数据' }],
  max_tokens: 4096,
  temperature: 0.1,
  api_key: process.env.VIKING_CHAT_API_KEY || undefined,
  stream: false,
})
console.log('chat_completion=', chatResp)

// SSE 流式对话
for await (const item of client.chatCompletionStream({
  model: 'Doubao-1-5-pro-32k',
  messages: [{ role: 'user', content: '总结下 2025 Q1 财报数据' }],
  stream: true,
})) {
  const delta = item.data?.generated_answer
  if (typeof delta === 'string' && delta) process.stdout.write(delta)
}

// ServiceChat（一般用 API Key）
const serviceClient = knowledge.createClient(knowledge.AuthAPIKey(process.env.VIKING_SERVICE_API_KEY || ''))
const serviceResp = await serviceClient.serviceChat({
  service_resource_id: process.env.VIKING_SERVICE_RID || '',
  messages: [{ role: 'user', content: '列举 2025 Q1 财报里的三项亮点' }],
  stream: false,
})
console.log('service_chat=', serviceResp)

请求级参数（超时/重试/请求头/Query/RequestID）

Vector 与 Knowledge 都支持请求级 options：

import * as vector from '@volcengine/vikingdb-sdk/vector'

await indexClient.searchByRandom(
  { limit: 1 },
  vector.WithRequestTimeoutMs(120_000),
  vector.WithRequestMaxRetries(0),
  vector.WithRequestHeader('X-Debug', '1'),
  vector.WithRequestID('my-request-id'),
)

服务端返回的 request id 字段一般在 resp.request_id，同时 SDK 也支持通过 Header X-Tt-Logid 注入/透传请求 ID。

错误处理与重试

• vector.VikingDBError / knowledge.KnowledgeError：SDK 抛出的结构化错误
• vector.isRetryableError / knowledge.isRetryableError：内部重试判定逻辑
• 全局默认重试次数由 ClientConfig.maxRetries 控制，也可通过请求级 WithRequestMaxRetries() 覆盖

Examples

npm 包内自带编译后的示例代码，位于 dist/examples/，可直接用 node 运行：

Vector

# 设置环境变量
export VIKINGDB_AK="your-access-key"
export VIKINGDB_SK="your-secret-key"
export VIKINGDB_COLLECTION="your-collection"
export VIKINGDB_INDEX="your-index"

# 通过 main.js 入口运行指定示例
node node_modules/@volcengine/vikingdb-sdk/dist/examples/vector/main.js connectivity

可用示例：connectivity / collection_lifecycle / index_search_multimodal / index_search_vector / search_by_keyword / search_aggregate / embedding / rerank

Knowledge

export VOLC_AK="your-access-key"
export VOLC_SK="your-secret-key"
export VIKING_COLLECTION_NAME="your-collection"
export VIKING_COLLECTION_RID="your-resource-id"

node node_modules/@volcengine/vikingdb-sdk/dist/examples/knowledge/main.js init_client

可用示例：init_client / doc_crud / point_crud / search / overall