Standardmäßig ist der Prompt ausgewählt, der zuerst die Quelle prüft. Sie können zu einem direkten Befehl wechseln oder eine lokale Kopie herunterladen.
Quelldateien prüfen
Lesen Sie SKILL.md und alle von SkillsMP angezeigten Begleitdateien, bevor Sie sich für eine Installation entscheiden.
Mit Codex oder Claude installieren Kopieren Sie diesen Prompt, fügen Sie ihn in Codex, Claude oder einen anderen Assistant ein und lassen Sie die Skill-Seite prüfen und installieren.
Ein direkter Befehl überspringt den Prüf-Prompt. Prüfen Sie die Quelle, bevor Sie ihn ausführen.
CLI for integrating Volcengine AI Search, recommendation, and conversational retrieval into agent and business systems
triggers
["integrate AI search into my application","set up Volcengine search CLI","configure AI-powered search and recommendations","onboard data to Volcengine AI Search","build conversational retrieval with SearchCLI","tune search quality with Viking","create item search with SearchCLI","run search evaluation and tuning"]
SearchCLI is the open-source CLI for Volcengine AI Search. It provides stable, tunable search, recommendation, and conversational retrieval capabilities for agent systems and business applications. Built with TypeScript, it offers agent-friendly workflows with installable skills, dry-runs, confirmation gates, and automated quality tuning.
What It Does
Item & Catalog Search: Build search on structured business data
Recommendation Flows: Connect recommendations to application scenes and user behavior
Conversational Retrieval: Create RAG-style chat experiences grounded in application search
Agent Workflows: Onboard data, configure applications, and validate behavior with reviewable steps
Automated Tuning: Text-similarity evaluation and query tuning with LLM-based relevance judging
Installation
Requirements
Node.js 20 or newer
Git
Volcengine AK/SK with AI Search access
Install SearchCLI
git clone git@github.com:volcengine/SearchCLI.git vs
cd vs
bash ./scripts/install.sh
If VIKING_AK and VIKING_SK are already in your environment:
vs auth import-env
vs auth status --json
Interactive Login
vs auth login
vs auth status --json
vs doctor --json
LLM Configuration (for Search Tuning)
For query generation and LLM-based relevance judging:
# Interactive setup
vs llm login
vs llm status --json
# Or import from environment# Requires: VIKING_LLM_BASE_URL, VIKING_LLM_API_KEY, VIKING_LLM_MODEL
vs llm import-env
vs llm status --json
Verify LLM connectivity:
vs search tune llm-check --live --json
Core Command Groups
Authentication & Setup
vs auth login # Interactive authentication
vs auth import-env # Import AK/SK from environment
vs auth status --json # Check auth status
vs llm login # Configure LLM for tuning
vs llm import-env # Import LLM config from env
vs doctor --json # System health check
Item Onboarding
vs item profile --file ./items.json --pretty
vs item plan --file ./items.json --goal "Build item search"
vs item apply --plan-dir ./.viking/item-plans/<plan> --dry-run
vs item apply --plan-dir ./.viking/item-plans/<plan> --confirm-review --wait-ready --run-trials
Dataset Management
vs dataset create --data @dataset-create.json
vs dataset ingest --dataset-id <id> --fields @<file>
vs dataset list --json
vs dataset describe --dataset-id <id> --json
Application Management
vs app list --json
vs app describe --app-id <id> --json
vs app create --data @app-config.json
vs app update --app-id <id> --data @update.json
Search Operations
vs search run --app-id <id> --query "search term" --json
vs search tune query-generate --dataset-id <id> --output ./queries.json
vs search tune plan --queries @queries.json --dataset-id <id>
vs search tune run --plan-dir ./plan --output ./results.json
vs search tune report --results @results.json --pretty
Recommendation
vs recommend run --app-id <id> --user-id <uid> --json
Conversational Retrieval
vs chat run --app-id <id> --query "What are the best products?" --json
Workflows
Dataset + App Provisioning (Full Onboarding)
Complete workflow for creating both dataset and search application:
# 1. Profile your data
vs item profile --file ./items.json --pretty
# 2. Generate provisioning plan
vs item plan --file ./items.json --goal "Build product search"# 3. Review plan with dry-run
vs item apply --plan-dir ./.viking/item-plans/<plan-id> --dry-run
# 4. Execute with confirmations and runtime verification
vs item apply \
--plan-dir ./.viking/item-plans/<plan-id> \
--confirm-review \
--wait-ready \
--run-trials
Dataset-Only Provisioning
When you only need data ingestion without application setup:
# Generate dataset-only plan
vs item plan --file ./items.json --goal "Ingest product data" --skip-app
# Create dataset
vs dataset create --data @dataset-create.json
# Ingest data
vs dataset ingest --dataset-id <dataset-id> --fields @<normalized-items-artifact>
The --skip-app flag works with vs item provision and vs item apply as a guardrail.
Video Dataset Provisioning
Always specify --type video explicitly for video datasets:
# Dataset + App
vs item profile --file ./videos.jsonl --type video --pretty
vs item plan --file ./videos.jsonl --type video --goal "Build video search"
vs item apply --plan-dir ./.viking/item-plans/<plan> --confirm-review --wait-ready
# Dataset-only
vs item plan --file ./videos.jsonl --type video --goal "Video data" --skip-app
vs dataset create --data @dataset-create.json
vs dataset ingest --dataset-id <id> --fields @<artifact>
Important: For video datasets, prefer dataset-create.json over --schema @schema.json to include DataFieldConfig and avoid MissingParameter.DefaultFieldStrategy errors.
Search Quality Tuning
Automated evaluation and tuning workflow:
# 1. Generate evaluation queries
vs search tune query-generate \
--dataset-id <dataset-id> \
--output ./eval-queries.json
# 2. Create tuning plan
vs search tune plan \
--queries @eval-queries.json \
--dataset-id <dataset-id>
# 3. Run evaluation
vs search tune run \
--plan-dir ./.viking/search-tune-plans/<plan-id> \
--output ./results.json
# 4. Generate report
vs search tune report \
--results @results.json \
--pretty
#!/bin/bashset -e
# Environment check
vs doctor --json
# 1. Profile and plan
vs item profile --file ./products.json --pretty
vs item plan --file ./products.json --goal "E-commerce product search"# Get the latest plan directory
PLAN_DIR=$(ls -dt ./.viking/item-plans/* | head -1)
# 2. Review with dry-run
vs item apply --plan-dir "$PLAN_DIR" --dry-run
# 3. Execute provisioning
vs item apply \
--plan-dir "$PLAN_DIR" \
--confirm-review \
--wait-ready \
--run-trials
echo"Onboarding complete. Check ./.viking/item-plans/ for artifacts."
# Required for authenticationexport VIKING_AK="your-access-key"export VIKING_SK="your-secret-key"# Optional: LLM for search tuningexport VIKING_LLM_BASE_URL="https://api.openai.com/v1"export VIKING_LLM_API_KEY="sk-..."export VIKING_LLM_MODEL="gpt-4"# Then import
vs auth import-env
vs llm import-env
Credential Storage
SearchCLI stores credentials securely:
API Keys: Local secure credential store (not plain text config)
LLM Base URL & Model: Stored as non-secret config
Plan Artifacts: ./.viking/ directory (safe to version control after removing sensitive data)
Output Formats
Most commands support --json for machine-readable output:
vs auth status --json
vs dataset list --json
vs search run --app-id <id> --query "test" --json
Use --pretty for human-readable formatting:
vs item profile --file ./items.json --pretty
vs search tune report --results @results.json --pretty
Common Patterns
Incremental Data Updates
# Update existing dataset
vs dataset ingest --dataset-id <id> --fields @new-items.json --mode append
# Replace all data
vs dataset ingest --dataset-id <id> --fields @all-items.json --mode replace
Multi-Stage Verification
# Always use dry-run first
vs item apply --plan-dir <plan> --dry-run
# Then execute with confirmations
vs item apply --plan-dir <plan> --confirm-review
# Add runtime trials for end-to-end verification
vs item apply --plan-dir <plan> --confirm-review --run-trials
Search Result Validation
# Run search and save results
vs search run \
--app-id <app-id> \
--query "test query" \
--json > search-results.json
# Use in scripts for validation
jq '.Results | length' search-results.json
# Check current auth status
vs auth status --json
# Re-authenticate
vs auth login
# Verify credentials are setecho$VIKING_AKecho$VIKING_SK# Full diagnostic
vs doctor --json
Dataset Creation Errors
Error: MissingParameter.DefaultFieldStrategy (common with video datasets)
# ❌ Don't use schema-only for video datasets
vs dataset create --name video-data --type video --schema @schema.json
# ✅ Use full create payload with DataFieldConfig
vs dataset create --data @dataset-create.json
Solution: Always use dataset-create.json from the plan artifact, which includes both Schema and DataFieldConfig.
Item Ingestion Issues
# Verify dataset exists and is ready
vs dataset describe --dataset-id <id> --json
# Check item data format
vs item profile --file ./items.json --pretty
# Use normalized artifact from plan
vs dataset ingest --dataset-id <id> --fields @<normalized-artifact>
LLM Connectivity Issues
# Check LLM configuration
vs llm status --json
# Test LLM connection
vs search tune llm-check --live --json
# Reconfigure if needed
vs llm login
Plan Execution Failures
# Always start with dry-run
vs item apply --plan-dir <plan> --dry-run
# Check plan artifactsls -la ./.viking/item-plans/<plan>/
# Review plan.json for detailscat ./.viking/item-plans/<plan>/plan.json | jq .
Search Tuning Not Working
# Verify LLM is configured
vs llm status --json
vs search tune llm-check --live --json
# Regenerate queries if format is wrong
vs search tune query-generate --dataset-id <id> --output ./new-queries.json
# Check plan directory structurels -la ./.viking/search-tune-plans/<plan>/
Permission Errors
# Verify AK/SK has correct permissions
vs doctor --json
# Check specific resource access
vs dataset list --json
vs app list --json
Agent Skill Installation
# List installed skills
vs skill list
# Reinstall all skills
vs skill install all
# Validate skill definitions
vs skill validate
Best Practices
Always use dry-run first: --dry-run shows what will happen without executing
Use confirmation gates: --confirm-review adds human review step for critical operations
Prefer dataset-create.json: Especially for video datasets, use full payloads over schema-only
Store credentials securely: Never commit AK/SK to version control; use environment variables
Version control plans: The .viking/ directory contains reproducible plans (clean sensitive data first)
Use JSON output for automation: --json flag provides machine-readable output
Validate with runtime trials: --run-trials ensures end-to-end functionality
Type video datasets explicitly: Always pass --type video for video data
