Ducky

Ducky 是什么

Ducky 是 Lyco.AI, Inc. 提供的全托管检索基础设施，帮助开发者为 RAG 应用和 AI 智能体建立索引、搜索文档并返回可供模型使用的上下文。团队不必自行部署向量数据库、切分管线、混合检索和重排服务。

本词条介绍的是面向开发者的 Ducky AI 搜索平台，不是 Duckie 客服智能体、同名命令行工具或其他搜索项目。Ducky 提供网页控制台、网络 API、Python 与 TypeScript SDK。

主要功能概览

Project、Index 与 Document

Project 是最高层级的资源和权限边界，一个 Project 可以包含多个 Index，API 密钥也与 Project 绑定。Index 是一组相关文档的集合，检索时需要指定目标 Index。

• 用不同 Project 隔离环境、客户或应用。
• 用不同 Index 隔离商品、帮助文档、工单或法规资料。
• 每个 Document 属于一个 Index，并可使用自定义文档编号。
• 正文是主要检索内容，标题和原始地址可作为辅助字段。
• 元数据保存类别、版本、权限、作者、评分和时间等结构化属性。
• API 密钥应只授予需要访问对应 Project 的服务。

Index 的设计比传统搜索引擎配置更简化，不要求用户预先定义复杂映射。简化配置也意味着团队仍需自行设计数据边界、权限字段、文档版本和同步策略。

文本与文件索引

开发者可以直接提交文本，也可以上传 PDF 和 UTF-8 文本文件。当前文件文档写明单文件最大 60MB，平台会提取内容后完成切分、向量化和索引。

• 正文 content 是文本索引的必需字段。
• title、原始地址、source document id 和 metadata 为可选字段。
• 元数据值支持字符串、数字和布尔类型。
• 批量索引单次最多提交 100 个文档。
• 异步 SDK 方法适合并行上传，但仍应控制客户端并发。
• upsert 使用同一文档编号创建或更新内容。
• 删除上游内容时，应同步调用删除接口并验证索引结果。

上传 PDF 前应确认扫描件是否包含可提取文本，并抽查表格、页眉和跨页段落。复杂版式即使成功索引，也可能产生顺序错误或缺少上下文的分块。

多模态图片索引

Ducky 的多模态索引可把图片与文本组合为可搜索文档，并自动提取视觉信息。当前支持 JPEG、PNG、GIF 和 WebP，图片可通过可访问地址或 Base64 内容提交。

• 适合搜索商品外观、图表、截图、设计素材和图文知识库。
• 自然语言查询可以匹配图片视觉内容和配套文字。
• 图片地址抓取当前有 10 秒超时限制。
• 使用 Base64 会增加请求体大小和传输成本。
• 图片中的细小文字、复杂图表和低清晰度内容可能识别不完整。
• 上传前应移除人脸、证件、密钥、客户数据等不必要敏感信息。

旧版数据加载文档仍写当前只支持文本，而较新的多模态文档与产品页已明确提供图片能力。这反映文档更新不同步，实际使用前应以当前 API 参考和账户功能为准。

检索流程与搜索类型

Ducky 将文档切成较小内容块并生成语义表示，再把分块和元数据写入 Index。查询时可以使用关键词、语义或混合检索，并可在最后执行重排。

alpha 参数用于平衡关键词与语义信号，top_k 控制返回数量，当前文档给出的范围是 1 至 100。团队应使用真实问题集评估召回率、顶部准确率、延迟和每次查询成本。

检索结果如何使用

Retrieve 可同时返回按文档聚合的结果和单独内容块，结果包含正文、元数据与相关性分数。应用可以选择最相关的分块加入大模型提示，也可以向用户展示对应文档。

• 文档结果便于展示完整记录和原始资料。
• 分块结果便于控制发送给大模型的上下文长度。
• 相关性分数适合排序和调试，不应当作事实正确率。
• 元数据可用于继续做权限、渠道和版本判断。
• 原始文档编号便于回到业务系统核验和更新。
• 生成回答时应保留被使用文档和分块的审计记录。

Ask 接口

Ask 接口把检索和答案综合封装在一个请求中，用户提交问题后，内部智能体可扩展搜索、跨文档推理并生成直接回答。响应包含置信度和关联文档，适合快速构建问答入口。

置信度不是法律、医疗或业务事实的保证，关联文档也可能过期、冲突或权限不当。高风险应用应保留原文检查、阈值、拒答、人工审批和可追踪引用。

完整接入教程

1. 注册账户并创建 Project，明确开发、测试和生产环境边界。
2. 在 Project 中创建 Index，并按数据用途和访问权限规划命名。
3. 创建专用 API 密钥，保存到服务器端密钥管理系统。
4. 安装 Python 或 TypeScript SDK，或选择直接调用网络接口。
5. 准备少量代表性文本、PDF 和元数据，先验证抽取与分块质量。
6. 提交索引任务并保存文档编号，检查列表和单文档读取结果。
7. 使用关键词、语义与混合检索测试真实用户问题。
8. 调整 alpha、top_k、过滤条件和是否重排，并建立离线评测集。
9. 把检索结果或 Ask 回答接入应用，同时实现权限与事实核验。
10. 监控索引和检索 token、失败请求、延迟、空结果与超额费用。
11. 建立更新和删除同步任务，定期轮换密钥并复查数据保存安排。

Python、TypeScript 与直接 API

Python 包当前版本为 0.12.0，TypeScript 包当前版本为 1.4.1。版本会继续变化，生产环境应锁定依赖、查看变更日志并在升级前执行回归测试。

API 密钥安全

• 不要把密钥写入浏览器前端、移动应用包或公开仓库。
• 按 Project 和环境分别创建密钥，避免跨客户共用。
• 在自有后端增加身份验证、请求限额和审计日志。
• 不要把用户传入的 Index 名称直接用于越权查询。
• 密钥泄露时立即撤销，并检查索引、检索和费用异常。
• 在日志中遮盖密钥、客户正文和敏感元数据。

价格与用量

索引和检索使用不同 token 额度与超额单价，不能只按文档数或查询数估算成本。文档长度、分块、返回上下文、重排和重复更新都会影响实际用量。

公开页面未明确 Trial 是否按月刷新、Launch 自动续费、未用额度结转、税费、失败请求、退款和取消规则。生产采购前应在结算页面或书面合同中确认这些事项。

成本控制建议

• 先对文档去重、清理模板页眉和无检索价值的重复内容。
• 用文档编号 upsert，避免把每次小更新都当成新文档。
• 为查询设置合理 top_k，不要默认取满 100 条。
• 只在需要提升排序质量时启用重排。
• 用元数据过滤缩小搜索范围并减少无关上下文。
• 缓存允许重复使用的检索结果，同时设置内容更新失效机制。
• 分别监控索引和检索 token，设置月度预算与超额告警。

GitHub、SDK 与开源状态

cookbook 公开并仍有更新，可用于学习法律文档问答、Slack 搜索等集成方式，但没有许可证时不能默认获得复制、修改和商用分发权。SDK 可下载安装同样不等于平台或包采用开放许可。

隐私、安全与数据保存

隐私政策说明会处理姓名、邮箱、电话、地址、IP、浏览器、设备、使用和诊断数据，并使用 Cookie、像素和类似技术。个人信息可用于提供账户、履行合同、通信、分析、改进和营销。

• 个人信息可能与服务商、关联方、业务伙伴和交易承接方共享。
• 数据可能在公司及处理方所在地区处理，保护法律可能与用户所在地不同。
• 个人数据按业务目的、争议和法律义务所需期限保存，没有统一公开时限。
• 用户可在账户中更新部分信息，也可申请访问、更正或删除。
• 公司承诺采取商业上合理的保护措施，但不保证绝对安全。
• 服务不面向 13 岁以下儿童。

条款称 Ducky 只连接用户主动提供的数据，并采取合理措施保护机密性。当前未公开明确的数据驻留区域、索引删除时限、备份策略、DPA、SOC 2、ISO 27001、加密细节或客户内容是否用于训练模型的完整承诺。

企业数据建议

• 不要在未签署数据处理协议前索引敏感个人信息或客户机密。
• 向服务方确认数据驻留、子处理商、训练用途和删除证明。
• 用元数据实施租户与权限过滤，但在应用后端再次强制鉴权。
• 为测试环境使用脱敏或合成数据，不复制完整生产知识库。
• 保留上游原始数据与索引清单，避免把托管索引当作唯一备份。
• 合同结束前导出必要映射，并验证文档、分块和备份删除流程。

准确性、版权与商用边界

Ducky 负责检索和基于索引生成答案，但用户仍需审核结果。搜索分数、重排结果和 Ask 置信度都不能证明答案真实、完整或适合高风险决策。

• 只索引团队有权处理和向外部服务传输的文档。
• 为客户内容、员工资料和受许可数据库确认合同权限。
• 搜索应用要在检索前后同时实施访问控制。
• 面向用户展示答案时提供原文定位和更新时间。
• 为冲突文档、无结果和低置信度建立拒答与人工复核。
• 条款未完整说明客户数据和生成输出权利，企业应书面确认。
• 平台自身不得在未获书面同意时复制、修改或分发。

适合用户与场景

• SaaS 开发团队：为产品加入帮助中心和应用内搜索。
• 智能体开发者：为工具调用和回答提供相关上下文。
• 电商团队：按自然语言、图片和元数据搜索商品。
• 企业知识团队：搜索手册、政策、会议记录和内部报告。
• 法务与合规团队：构建带原文核验的条款问答原型。
• 客服产品：检索工单、产品文档和解决方案知识。
• 数据团队：快速验证关键词、语义、混合和重排策略。

优势与主要限制

主要优势

• 托管索引、分块、语义搜索和重排，减少自建基础设施。
• 同时提供关键词、语义、混合搜索和复杂元数据过滤。
• 支持文本、PDF、文本文件和多模态图片。
• Python、TypeScript 与直接 API 覆盖常见接入方式。
• Ask 接口能直接返回答案、置信度和关联文档。
• 免费额度允许先用真实小数据集验证质量。

主要限制

• 索引和检索采用不同 token 计费，成本需分别监控。
• 混合权重、分块、元数据和权限仍需要团队设计与评测。
• Ask 生成答案可能不准确，不能替代原文和专业审核。
• 部分旧文档与新多模态页面的支持范围不同步。
• 数据驻留、认证、训练用途和删除细节公开信息不足。
• 平台闭源，公开 cookbook 和 SDK 当前没有检测到许可证声明。

总结

Ducky 适合希望快速为 AI 产品接入托管文档索引、混合检索、重排和问答接口，而不愿自行维护搜索集群的开发团队。上线前应重点验证真实数据质量、权限隔离、两类 token 成本、隐私合同、删除流程和无许可证示例代码的使用边界。

常见问题

Ducky 是什么类型的工具？

它是全托管 RAG 检索基础设施，提供文档索引、关键词与语义搜索、重排和直接问答接口，主要通过 API 和 SDK 接入应用。

Ducky 可以免费使用吗？

可以试用，Trial 当前包含 10 万索引 token 和 10 万检索 token。公开页面没有明确这些额度是否会定期刷新。

Launch 套餐多少钱？

当前为每月 290 美元，包含每月 300 万索引 token 和 300 万检索 token，以及 Slack 专属支持。

超额用量如何收费？

索引超额为每 1K token 0.014 美元，检索超额为每 1K token 0.079 美元。应分别设置监控和预算。

支持 PDF 和图片吗？

支持 PDF、文本文件和多模态图片。图片格式包括 JPEG、PNG、GIF 和 WebP，文件与图片限制需按当前接口核对。

支持哪些检索方式？

支持关键词、语义和混合检索，可用 alpha 调整权重，并支持元数据过滤和可选重排。

Ask 接口与普通检索有什么区别？

普通检索返回文档和分块，Ask 会继续综合答案并返回置信度和关联文档。两者都需要应用自行做权限与事实审核。

有 Python 和 TypeScript SDK 吗？

有，Python 包名为 duckyai，TypeScript 包名为 duckyai-ts。也可以用标准网络请求直接调用 API。

ducky-cookbook 开源吗？

仓库公开可读，但当前未检测到许可证文件或 SPDX 标识。公开不等于获得修改、商用和再分发授权。

Ducky 平台开源吗？

不开源，条款将平台、算法和相关技术列为公司知识产权。SDK 和示例仓库公开也不改变平台的闭源属性。