← Back to Blog
多模态向量化功能说明
本项目已支持使用火山引擎API进行文本和图片的向量化处理，实现多模态知识库搜索。
功能特性
- ✅ 支持文本文件向量化（PDF、TXT、DOC、CSV）
- ✅ 支持图片文件向量化（JPEG、PNG、GIF、WebP）
- ✅ 支持文本查询
- ✅ 支持图片相似性搜索
- ✅ 支持混合搜索（文本+图片）
支持的文件类型
文本文件
text/plain- 纯文本文件application/pdf- PDF文档application/msword- Word文档（.doc）application/vnd.openxmlformats-officedocument.wordprocessingml.document- Word文档（.docx）text/csv- CSV文件
图片文件
image/jpeg/image/jpg- JPEG图片image/png- PNG图片image/gif- GIF图片image/webp- WebP图片
API使用说明
文件处理
import { processFile } from './lib/vectorization'
// 处理任意支持的文件（自动检测文本或图片）
await processFile(fileId)文本搜索
import { searchSimilarChunks } from './lib/vectorization'
// 使用文本查询搜索
const results = await searchSimilarChunks(
"查找相关的产品图片",
knowledgeBaseId,
10
)图片搜索
import { searchSimilarImages, searchSimilarChunks } from './lib/vectorization'
// 方法1: 使用专门的图片搜索函数
const results1 = await searchSimilarImages(
"https://example.com/image.jpg",
knowledgeBaseId,
10
)
// 方法2: 使用通用搜索函数
const imageQuery = {
type: "image_url",
image_url: {
url: "https://example.com/image.jpg"
}
}
const results2 = await searchSimilarChunks(imageQuery, knowledgeBaseId, 10)混合搜索
import { hybridSearch } from './lib/vectorization'
// 同时使用文本和图片搜索
const results = await hybridSearch(
knowledgeBaseId,
"产品设计", // 文本查询
"https://example.com/design.jpg", // 图片查询
10
)
// 仅使用文本
const textResults = await hybridSearch(
knowledgeBaseId,
"用户界面",
undefined,
10
)
// 仅使用图片
const imageResults = await hybridSearch(
knowledgeBaseId,
undefined,
"https://example.com/ui.jpg",
10
)火山引擎API配置
输入格式
文本输入
{
"type": "text",
"text": "要向量化的文本内容"
}图片输入
{
"type": "image_url",
"image_url": {
"url": "https://example.com/image.jpg"
}
}API请求示例
{
"model": "ep-20250531230449-wtdzd",
"input": [
{
"type": "image_url",
"image_url": {
"url": "https://ark-project.tos-cn-beijing.volces.com/images/view.jpeg"
}
}
]
}注意事项
- 图片编码方式: 默认使用Base64编码，无需配置公网URL
- API限流: 图片处理时增加了延迟（200ms）以避免API限流
- 批处理大小: 图片处理时使用较小的批处理大小（5个/批）
- 文件大小限制: 建议图片文件小于10MB，过大的图片可能导致API调用失败
- 支持格式: 支持JPEG、PNG、GIF、WebP格式
配置要求
环境变量
# 火山引擎API配置
ARK_API_KEY=your-api-key
ARK_API_URL=https://ark.cn-beijing.volces.com/api/v3/embeddings/multimodal
EMBEDDING_MODEL=your-endpoint-id
# 图片服务配置（可选，现在默认使用Base64编码）
# BASE_URL=https://your-domain.com数据库字段
确保 vectorChunk 表支持存储图片相关的元数据：
-- metadata 字段应该支持 JSON 格式，包含：
{
"isImage": true,
"imageUrl": "https://example.com/image.jpg",
"fileName": "image.jpg",
"chunkIndex": 0,
"totalChunks": 1,
"useBase64": false
}最佳实践
- 图片预处理: 考虑对大图片进行压缩以提高处理速度
- 缓存策略: 对向量结果进行缓存以避免重复计算
- 错误处理: 实现适当的重试机制处理API调用失败
- 相似度计算: 考虑实现客户端相似度计算以减少API调用次数
故障排除
常见错误及解决方案
1. Base64图片格式错误
错误信息: Base64图片格式错误或图片过大
原因: 图片文件格式不支持或文件过大
解决方案:
- 确保使用支持的格式：JPEG、PNG、GIF、WebP
- 压缩图片文件大小（建议小于10MB）
- 检查图片文件是否损坏
2. Next.js 参数访问错误
错误信息: params should be awaited before using its properties
解决方案: 已修复，确保在API路由中先 await params
3. 图片文件过大
错误信息: API超时或内存不足
解决方案:
- 压缩图片文件
- 使用适当的图片格式
- 考虑分批处理
4. API限流
错误信息: 429 Too Many Requests
解决方案:
- 增加请求间隔（已实现200ms延迟）
- 减少批处理大小
- 实现指数退避重试
调试技巧
- 检查环境变量:
echo $BASE_URL
echo $ARK_API_KEY- 测试图片URL可访问性:
curl -I $BASE_URL/uploads/knowledge/your-file.jpg- 查看详细日志:
// 在向量化过程中会输出详细日志
console.log("图片处理方式: Base64编码/URL访问")
console.log("Generated image URL: https://...")- 验证API响应:
// 检查API返回的向量维度
console.log("向量维度:", embedding.length)性能优化
-
图片优化:
- 使用WebP格式减少文件大小
- 限制图片分辨率（建议不超过2048x2048）
- 压缩图片质量
-
批处理优化:
- 图片处理使用较小批次（5个/批）
- 文本处理可使用较大批次（10个/批）
-
缓存策略:
- 缓存向量结果避免重复计算
- 使用Redis等缓存系统
示例代码
参考 lib/vectorization-examples.ts 文件查看完整的使用示例。