list_docs--向量数据库VikingDB-火山引擎

文档中心

向量数据库VikingDB

文档（Doc）

list_docs

概述

list_docs 用于查询知识库上文档的列表，默认按照文档的上传时间倒序。

请求参数

参数	子参数	类型	是否必选	默认值	参数说明
collectionName	--	String	否	--	知识库名称
projectName	--	String	否	default	知识库所属项目，获取方式参见文档API 接入与技术支持若不指定该字段，则在default项目下创建。若需要操作指定项目下的知识库，需正确配置该字段。
resourceId	--	String	否	--	知识库唯一 id 可选择直接传 ResourceID，或同时传 CollectionName 和 ProjectName 作为知识库的唯一标识
filter		Map<String, Object>	否	--	过滤条件用于对返回结果进行过滤，支持使用 doc_id 过滤
	docIdList	String[]	否	--	指定 doc_id 过滤条件只返回列表中指定的文档信息
offset	--	Integer	否	0	查询起始位置表示从结果的第几个文档后开始取，需要大于等于0 注：如果设置 Offset ≥ 100，需同时传入 Limit 参数才能生效
limit	--	Integer	否	-1	查询文档数 -1 表示获取所有，最大值不超过 100，每次返回最多不超过 100
docType	--	String	否	--	文档类型筛选
returnTokenUsage	--	Boolean	否	false	是否返回文档向量化和文档摘要生成所消耗的 tokens

响应消息

字段	类型	参数说明
code	Integer	状态码
message	String	返回信息
requestId	String	标识每个请求的唯一标识符
data	ListDocsResult	ListDocsResult

ListDocsResult

字段	类型	参数说明
docList	List	文档信息列表
count	Integer	本次查询返回的文档总数
totalNum	Integer	该知识库下的文档总数

DocInfo

字段	类型	参数说明
collectionName	String	知识库名称
docName	String	文档名称
docId	String	文档 id
docHash	String	文档 hash
addType	String	导入方式
docType	String	文档类型
description	String	文档描述（当前仅支持图片文档）
createTime	Long	文档创建时间
addedBy	String	添加人
updateTime	Long	文档更新时间
url	String	原始文档链接
tosPath	String	tos 路径
pointNum	Integer	切片数量
status	DocStatus	DocStatus
title	String	文档标题
source	String	知识来源（url，tos 等）
totalTokens	Object	token 统计
docSummaryTokens	Integer	摘要 token 统计
docPremiumStatus	DocPremiumStatus	DocPremiumStatus
docSummary	String	文档摘要
briefSummary	String	简要摘要
docSize	Integer	文档大小
meta	String	meta 信息
labels	Map<String, String>	标签信息
videoOutline	Map<String, Object>	视频大纲
audioOutline	Map<String, Object>	音频大纲
statistics	Map<String, Object>	统计信息
project	String	项目名
resourceId	String	知识库唯一 id

DocStatus

字段	类型	参数说明
processStatus	Integer	处理状态
failedCode	Integer	失败错误码
failedMsg	String	失败错误信息

DocPremiumStatus

字段	类型	参数说明
docSummaryStatusCode	Integer

状态码说明

状态码	http状态码	返回信息	状态码说明
0	200	success	成功
1000001	401	unauthorized	鉴权失败
1000002	403	no permission	权限不足
1000003	400	invalid request：%s	非法参数
1000005	400	collection not exist	collection不存在

请求示例

首次使用知识库 SDK ，可参考使用说明
本示例演示了知识库 Java SDK 中 ListDocs 的基础使用方法，通过指定知识库信息实现文档列表查询，使用前需配置鉴权参数（VOLC_AK/VOLC_SK 或 VIKING_API_KEY）。

package com.volcengine.vikingdb.runtime.knowledge.examples.doc_list;

import com.fasterxml.jackson.databind.ObjectWriter;
import com.volcengine.vikingdb.runtime.core.ApiClient;
import com.volcengine.vikingdb.runtime.core.RequestAddition;
import com.volcengine.vikingdb.runtime.core.auth.Auth;
import com.volcengine.vikingdb.runtime.core.auth.AuthWithAkSk;
import com.volcengine.vikingdb.runtime.core.auth.AuthWithApiKey;
import com.volcengine.vikingdb.runtime.enums.Scheme;
import com.volcengine.vikingdb.runtime.knowledge.model.CollectionMeta;
import com.volcengine.vikingdb.runtime.knowledge.model.request.ListDocsRequest;
import com.volcengine.vikingdb.runtime.knowledge.model.response.ListDocsResponse;
import com.volcengine.vikingdb.runtime.knowledge.service.KnowledgeCollectionClient;
import com.volcengine.vikingdb.runtime.knowledge.service.KnowledgeService;

public class Main {
    private static final ObjectWriter PRETTY_JSON = ApiClient.objectMapper.writerWithDefaultPrettyPrinter();
    private static final Scheme SCHEME = Scheme.HTTPS;
    private static final String HOST = "api-knowledgebase.mlp.cn-beijing.volces.com";
    private static final String REGION = "cn-beijing";
    private static final String PROJECT = "default";
    private static final String COLLECTION_NAME = "your_collection_name";
    private static final String COLLECTION_RESOURCE_ID = "";

    public static void main(String[] args) throws Exception {
        Auth auth = preferAuth();
        if (auth == null) {
            System.out.println("missing_auth: set VOLC_AK/VOLC_SK or VIKING_API_KEY");
            return;
        }
        KnowledgeService service = newKnowledgeService(auth);
        KnowledgeCollectionClient kc = service.collection(defaultCollectionMeta());

        ListDocsRequest req = ListDocsRequest.builder()
                .offset(0)
                .limit(10)
                .returnTokenUsage(true)
                .build();

        ListDocsResponse resp = kc.listDocs(req, new RequestAddition());
        printJson("list_docs", resp);
    }

    private static KnowledgeService newKnowledgeService(Auth auth) {
        return new KnowledgeService(SCHEME, HOST, REGION, auth);
    }

    private static Auth preferAuth() {
        String ak = getEnv("VOLC_AK");
        String sk = getEnv("VOLC_SK");
        if (!ak.isEmpty() && !sk.isEmpty()) {
            return new AuthWithAkSk(ak, sk);
        }
        String apiKey = getEnv("VIKING_API_KEY");
        if (!apiKey.isEmpty()) {
            return new AuthWithApiKey(apiKey);
        }
        return null;
    }

    private static CollectionMeta defaultCollectionMeta() {
        return CollectionMeta.builder()
                .collectionName(COLLECTION_NAME)
                .projectName(PROJECT)
                .resourceId(COLLECTION_RESOURCE_ID)
                .build();
    }

    private static String getEnv(String name) {
        String v = System.getenv(name);
        if (v == null) {
            return "";
        }
        v = v.trim();
        return v.isEmpty() ? "" : v;
    }

    private static void printJson(String name, Object obj) throws Exception {
        if (obj == null) {
            System.out.println(name + ": null");
            return;
        }
        System.out.println(name + ": " + PRETTY_JSON.writeValueAsString(obj));
    }
}

最近更新时间：2026.03.26 17:20:14

这个页面对您有帮助吗？

有用

无用

向量数据库VikingDB

ListDocsResult #

DocInfo #

DocStatus #

DocPremiumStatus #

状态码说明 #

ListDocsResult

DocInfo

DocStatus

DocPremiumStatus

状态码说明