← Back to Skills Marketplace
volcengine-skills

Byted Bytehouse Multimodal Search

by volcengine-skills · GitHub ↗ · v1.0.0 · MIT-0
cross-platform ⚠ suspicious
97
Downloads
0
Stars
0
Active Installs
1
Versions
Install in OpenClaw
/install byted-bytehouse-multimodal-search
Description
ByteHouse 多模态检索 Skill,支持文本、图片、视频的向量化存储和混合检索。当用户需要在ByteHouse数据库中进行多模态向量化存储和混合检索时,使用此Skill。
README (SKILL.md)

ByteHouse 多模态检索 Skill

🚀 快速开始

环境准备

pip install clickhouse-connect volcengine-python-sdk[ark] numpy

环境变量配置

优先从环境变量读取配置,禁止硬编码明文敏感信息

# ByteHouse 配置
export BYTEHOUSE_HOST="\x3C你的ByteHouse连接地址>"
export BYTEHOUSE_PORT="\x3CByteHouse端口>"
export BYTEHOUSE_USER="\x3CByteHouse用户名>"
export BYTEHOUSE_PASSWORD="\x3CByteHouse密码>"
export BYTEHOUSE_DATABASE="\x3C默认数据库,可选,默认default>"
export BYTEHOUSE_SECURE="\x3C是否启用加密,可选,默认true>"

# 火山引擎方舟 API 配置
export ARK_API_KEY="\x3C火山引擎方舟API密钥>"
export ARK_BASE_URL="https://ark.cn-beijing.volces.com/api/v3"
export EMBEDDING_MODEL="doubao-embedding-vision-251215"
export EMBEDDING_DIMENSIONS="1536"  # 可选,默认1536

如果环境变量未配置,会自动提示用户输入。


📚 核心能力

1. 多模态向量化

基于豆包多模态向量化模型 doubao-embedding-vision-251215

输入类型 支持格式 最大限制
文本 纯文本字符串 无长度限制
图片 JPG/PNG/GIF/WEBP/BMP \x3C10MB,宽高>14px
视频 MP4/AVI/MOV \x3C50MB

关键约束

  • 多模态向量化必须调用 /embeddings/multimodal 接口
  • 图片/视频输入格式:{"type": "image_url", "image_url": {"url": "xxx"}}
  • 部分模型不支持 dimensions 参数

2. 向量检索功能

功能 方法 说明
纯向量检索 vector_search() 基于向量相似度检索
混合检索 hybrid_search() 向量+全文检索融合
以文搜图 text_search_image() 文本搜索图片
以图搜图 image_search_image() 图片搜索相似图片
以文搜视频 text_search_video() 文本搜索视频

📖 代码实现

完整示例代码实现位于 scripts/ 目录:

快速使用

from scripts import ByteHouseMultimodalSearch

# 初始化客户端
search = ByteHouseMultimodalSearch(connection_type="http")

# 创建表
search.create_multimodal_table("my_index")

# 插入文档
search.insert_document("my_index", doc_id=1, content_type="text", 
                      content="ByteHouse 多模态检索", title="介绍")

# 向量检索
results = search.vector_search("my_index", query_embedding=embedding, top_k=10)

⚙️ 最佳实践

索引选择

数据规模 索引类型 适用场景
\x3C100万 HNSW 中小规模,低延迟
100万-1亿 HNSW_SQ 大规模,平衡性能成本
>1亿 IVF_PQ_FS 超大规模

性能优化

SETTINGS 
    index_granularity = 1024,
    index_granularity_bytes = 0,
    enable_vector_index_preload = 1

指令优化

场景 Query 侧指令
通用文搜图 Target_modality: image. Instruction:根据文本描述找到对应的图片.
电商商品检索 Target_modality: image. Instruction:找到和描述匹配的同款商品图片.
原图检索 Target_modality: image. Instruction:查找和本图完全相同的图片.

❓ 常见问题

Q1: 向量维度怎么选?

  • 推荐 1536 维作为通用值
  • 维度越高精度越高,但成本也越高

Q2: 如何处理低召回问题?

  1. 增大 hnsw_ef_s 参数

Q3: API 调用失败排查

  • 404: 检查路径是否为 /embeddings/multimodal
  • 400: 检查输入格式,部分模型不支持 dimensions
  • 401: 检查 ARK_API_KEY 是否正确
  • 429: 降低请求频率

🔗 参考文档

Usage Guidance
This skill appears to implement the ByteHouse + Volcano Engine Ark multimodal search it claims, but there are important caveats to review before installing or running it: - Registry metadata omission: The registry declares no required env vars or primary credential, but the code needs ARK_API_KEY (for embeddings) and BYTEHOUSE_* credentials (host, user, password, database). Treat this omission as a transparency issue — do not provide high-privilege credentials without verifying the source. - Limit credentials and scope: Create and supply least-privilege credentials (a ByteHouse user limited to the specific database/tables and an API key with only embedding permission) rather than root/admin DB credentials. - Review and test code locally: The package includes Python scripts. Inspect them (you already have them) and run in a sandboxed environment before giving it network access or real credentials. - Beware SQL construction: insert_document and other methods build SQL using f-strings and interpolate table_name and content; avoid passing untrusted values or sanitize inputs first to prevent injection or malformed SQL. - Verify third-party packages: SKILL.md instructs pip installing clickhouse-connect and volcengine-sdk. Confirm these are the official packages, and consider installing into an isolated virtual environment. - MCP client behavior: The code tries to use an mcp_client if present (it may call other tools or skills). If you rely on MCP, understand what that client does; if unsure, initialize the search client with prefer_mcp=False. - Network/data exfiltration: The skill will send content (text/image/video URLs) and embeddings to external Ark endpoints and connect to your ByteHouse instance. Do not pass sensitive data (personal data, secrets) unless you accept that it will be transmitted to those endpoints. If you need higher assurance: ask the publisher for an explicit list of required env vars in the registry and for a signed package or known homepage. If you cannot verify the source, run in a restricted environment or decline installation.
Capability Analysis
Type: OpenClaw Skill Name: byted-bytehouse-multimodal-search Version: 1.0.0 The skill bundle provides multimodal search capabilities using ByteHouse and Volcengine Ark API, but it contains a significant SQL injection vulnerability. In `scripts/search_client.py`, multiple methods (such as `vector_search`, `hybrid_search`, and `_execute_sql`) construct SQL queries using f-strings with inadequate sanitization. Specifically, the `filter_condition` and `query_text` parameters are directly interpolated into SQL strings, which could allow an attacker or a malicious prompt to execute unauthorized database commands. While the code follows its stated purpose and lacks evidence of intentional malice or data exfiltration, the high-risk nature of the SQL injection flaw warrants a suspicious classification.
Capability Assessment
Purpose & Capability
The implementation matches the stated purpose: it calls a Volcano Engine (Ark) embeddings API and interacts with ByteHouse (ClickHouse) to create tables, insert embeddings, and run searches. However the registry metadata declares no required environment variables or primary credential even though the code clearly expects ARK_API_KEY and ByteHouse connection credentials (BYTEHOUSE_HOST, BYTEHOUSE_USER, BYTEHOUSE_PASSWORD, etc.). That omission is an inconsistency to be aware of.
Instruction Scope
SKILL.md reasonably limits instructions to installing Python dependencies and setting environment variables for ByteHouse and Ark. It does not attempt to access unrelated system files. Minor mismatch: SKILL.md claims the skill will 'prompt' the user if env vars are not set, but the provided code reads os.environ and does not implement prompting; that could lead to runtime failures or unexpected behavior when env vars are absent. The code also attempts to import/use an MCP client (mcp_client) if available, which will cause network interactions and delegation to another client if present—this is within scope but worth noting.
Install Mechanism
There is no formal install spec in the registry (instruction-only install), but SKILL.md requests pip installs (clickhouse-connect, volcengine-python-sdk[ark], numpy). Installing dependencies via pip is common and traceable to PyPI, but the package names should be verified for authenticity. Because the skill ships Python code files in the package, the skill will run code on the host when invoked — review the included files before executing.
Credentials
The environment access required by the code (ARK_API_KEY, ARK_BASE_URL, EMBEDDING_MODEL, EMBEDDING_DIMENSIONS and multiple BYTEHOUSE_* credentials) is proportionate to the declared functionality. The concern is that the registry metadata lists no required env vars or primary credential; this mismatch reduces transparency and increases the chance of accidental credential exposure. Additionally, the client constructs SQL and table names via Python f-strings without full sanitization, which can lead to SQL-injection-like risks if untrusted input is provided (table_name and content are interpolated).
Persistence & Privilege
The skill does not declare always:true and it does not request persistent/privileged system modifications. It does attempt to prefer an MCP client and may connect out to remote services at runtime, but there is no code that modifies other skills or system-wide settings.
How to Use
  1. Make sure OpenClaw is installed (local or Docker)
  2. Run the install command in chat: /install byted-bytehouse-multimodal-search
  3. After installation, invoke the skill by name or use /byted-bytehouse-multimodal-search
  4. Provide required inputs per the skill's parameter spec and get structured output
Version History
v1.0.0
ByteHouse 多模态检索 Skill 首次发布,支持文本、图片、视频的向量化存储与混合检索: - 支持通过环境变量安全配置 ByteHouse 与火山引擎方舟 API 参数。 - 提供多模态向量化能力,兼容文本、主流图片及视频格式。 - 实现多模态检索方法,包括向量检索、混合检索、以文搜图/视频、以图搜图。 - 附带示例代码及核心模块入口,便于快速集成使用。 - 提供索引/性能优化建议及常见问题解答。
Metadata
Slug byted-bytehouse-multimodal-search
Version 1.0.0
License MIT-0
All-time Installs 0
Active Installs 0
Total Versions 1
Frequently Asked Questions

What is Byted Bytehouse Multimodal Search?

ByteHouse 多模态检索 Skill,支持文本、图片、视频的向量化存储和混合检索。当用户需要在ByteHouse数据库中进行多模态向量化存储和混合检索时,使用此Skill。 It is an AI Agent Skill for Claude Code / OpenClaw, with 97 downloads so far.

How do I install Byted Bytehouse Multimodal Search?

Run "/install byted-bytehouse-multimodal-search" in the OpenClaw or Claude Code chat to install it in one step — no extra setup required.

Is Byted Bytehouse Multimodal Search free?

Yes, Byted Bytehouse Multimodal Search is completely free, licensed under MIT-0. You can download, install and use it at no cost.

Which platforms does Byted Bytehouse Multimodal Search support?

Byted Bytehouse Multimodal Search is cross-platform and runs anywhere OpenClaw / Claude Code is available (cross-platform).

Who created Byted Bytehouse Multimodal Search?

It is built and maintained by volcengine-skills (@volcengine-skills); the current version is v1.0.0.

💬 Comments