SuperAPI AI Directory
Partner中文AI newsFavorites
Skillsbailian-kb

bailian-kb

Data & analytics

View repository

Updated 11-02 13:14

About this skill

Bailian Knowledge Base Management (bl)

Division of labor between the retrieval side and the management side:Use kb_search(retrieve evidence) / kb_chat(finished Q&A) native tools to look up knowledge; this skill only covers the long tail of management—the full knowledge base lifecycle, documents, retrieval services, Chunks, and the data center.

This skill is not responsible fordetermining when retrieval should happen. The list of available retrieval services (including agent_id) is automatically injected into the session context by the plugin,kb_search / kb_chat use it directly; you do not need to load this skill first in order to retrieve.

Behavioral semantics of the retrieval service list

  • The list is pulled from the Bailian API by the plugin and then cached; it is refreshed periodically per session (about every 30 minutes) and contains only services in the deployed state;
  • A service just created or deployed with bl will not appear in the list immediately. You do not need to wait for a refresh—the agent_id just obtained in the command output can be used directly;
  • When there are many services, the list only shows the most recently modified several entries and indicates the total count. To find a specific service, use bl knowledge service list --scene search --name <关键词>；
  • When the list truly contains no service that can answer the user's question, tell the user truthfully,do not pick the most similar agent_id and try it。

Execution entry and configuration

Below, bl knowledge … is a command syntax example; actual operations are always performed through kb_manage, splitting the part after bl knowledge into an argument array. For example, bl knowledge service list --scene search corresponds to kb_manage({"args":["service","list","--scene","search"]})。

Do not run knowledge base commands directly through the shell, do not read credentials or use bl auth login / bl config set. The plugin automatically uses dsh's current credentials, Workspace, and fixed endpoint; when configuration is missing, guide the user to fill it in on the dsh plugin settings page. Arguments must not contain --api-key、--workspace-id、--base-url or --config。

Use kb_manage({"args":["list","--help"]}) to check the command. If the host does not have bl installed, install bailian-cli and then retry. When unsure about arguments, first check the corresponding command's --help; do not guess.

For operations that require confirmation, such as deletion, keep the CLI's original confirmation mechanism; when requires_confirmation appears, confirm with the user and do not automatically add --yes。

When to use which command

User intent Command Remarks
Look up knowledge / Q&A (daily retrieval) Native tool kb_search / kb_chat Does not go through bl
Create / view / rename / delete knowledge base / monitor bl knowledge create/list/info/update/delete/stats bl knowledge create --help
Upload local documents, check parsing status, delete documents, add tags bl knowledge doc upload/list/status/delete/tag bl knowledge doc upload --help
Batch import from OSS bl knowledge doc import-oss The Bucket must be pre-authorized for the service role
Create / deploy / tune retrieval (Q&A) services bl knowledge service create/update/deploy/… bl knowledge service --help
Fix incorrect chunks, block a certain piece of content bl knowledge chunk add/list/update/delete bl knowledge chunk --help
Data center category / file / collection management bl knowledge category/file/collection … bl knowledge category --help
CLI configuration, upgrade bl config show/set、bl update bl config --help
Post-deployment verification, debugging draft-version services bl knowledge search/chat --agent-version beta bl knowledge search --help

Core workflow: from creating a knowledge base to making it retrievable

bl knowledge doc upload --file ./docs/                # 1. 上传本地文件/目录 → 得 fileId
bl knowledge create --name my-kb --description '产品文档' --doc-id <fileId> --wait                # 2. 建库并导入 → 得 index-id (pipelineId)
bl knowledge service create --name my-search --scene search --index-id <index-id>   # 3. 建检索服务 → 得 agent-id（draft）
bl knowledge service deploy --agent-id <agent-id>                           # 4. 发布服务（此后可被默认版本调用）
bl knowledge service list --scene search --status deployed                  # 5. 确认服务可见

After deployment is complete, use the native tool kb_search with that agent_id Verify retrieval; to debug a draft configuration before deployment, use bl knowledge search --agent-id <id> --agent-version beta。

Shorthand for ingesting an existing file again:bl knowledge doc upload --file ./a.md --index-id <index-id> --wait(upload + import in one step).

ID quick reference (highly error-prone)

ID Source Where used
index-id knowledge create returned pipelineId / knowledge list The --index-id
fileId doc upload / doc import-oss returned by Data center commands (file get/delete、knowledge create --doc-id、doc tag）
doc_id(in-library document ID) doc list output doc delete、chunk add/update 's --doc-id；may carry a workspace suffix, ≠ fileId
job-id ingestionId returned by the import command doc status(must supply both --index-id and --job-id）
chunk id chunk list output's metadata._id chunk update/delete 's --chunk-id
agent-id service create/list service *、kb_search/kb_chat、bl knowledge search/chat

Command reference

Before running an unfamiliar command, run bl <命令> --help to view the full Usage / Flags / Notes / Examples.Do not guess flags. All commands support --output json(structured output),--dry-run(preview request),--quiet、--verbose。

Dangerous and irreversible operations

Confirm with the user before performing the following operations; only when scripting, use --yes to skip interactive confirmation:

  • knowledge delete: irreversible; the library and all index content are permanently deleted (data center source files are retained).
  • file delete: irreversible, and knowledge base document indexes referencing this file will become invalid; to remove it from just a single library, use doc delete。
  • chunk delete: irreversible.
  • service deploy: publishing affects online callers;service delete after that, agent_id can no longer be used (soft delete, idempotent).
  • collection create：No delete API, so be cautious when creating datasets.
  • Index configuration (embedding model, chunk size, etc.) cannot be changed after the library is created; it can only be rebuilt.

Best practices

  • When creating a service, the name must be written clearly：service create --name 's name is the main basis for the model to determine "what this service can look up" (the service description is not yet returned by the list API).检索服务1 Semantically meaningless names like this will make subsequent retrieval unable to route; write 产品文档检索、HR制度问答 names like this that show the covered content. Also fill in --description(≤1000 characters); once the list API returns this field, it will take effect automatically.
  • Services have two states, draft/deployed: only deployed can be called by the default version, and only deployed enters the service list the model sees; for draft debugging use --agent-version beta. To change the configuration of a published version: first modify the beta draft (service update), then after verification service deploy publish a new version.
  • Import-type commands (knowledge create、doc upload --index-id、doc status) should preferably include --wait to poll to the terminal state, avoiding manual polling; document parsing failures (e.g. PARSE_FAILED) will pass through the error with a non-zero exit code.
  • chunk add has a 10 QPS rate limit, so batch scripts should throttle; the response does not include a chunk id, so chunk list is needed to look it up.
  • service list must include --scene chat|search, and the two scenarios must be queried separately.