Kodda 文档
构建、发布和运营有据可依的 AI 助手，配额清晰可控。
本页与 Kodda 服务端行为保持一致：方案、文档导入限制、API 请求合约和安全策略。
快速开始
- 创建工作空间并激活付费方案（默认为免费方案）。
- 创建一个知识库并上传源文件（单个文件最大 5MB）。
- 创建一个助手并关联一个或多个知识库。
- 发布助手以获取公开链接或网站嵌入。
- 如需私有编程访问，在 Pro 方案创建 API 密钥并调用 /api/chat。
RAG 管道
文档上传
验证 MIME 类型和文件签名，然后保存处理记录。
文本提取
将 PDF/DOCX/DOC/TXT/MD/CSV/JSON/XLSX/HTML/PPTX 解析为纯文本。
分块 + 嵌入
将文本切分为块，通过 OpenAI 兼容嵌入 API 生成向量。
向量搜索
通过语义相似度和可选重排序检索最相关的内容块。
有据响应
生成回答和来源列表，配合月度用量管控。
方案矩阵（公开 Beta）
限制在助手、知识库、文档和聊天 API 中由服务端强制执行。Pro 方案包含 7 天免费试用。
| 功能 | Free | Pro |
|---|---|---|
| 助手 | 1 | 3 |
| 知识库 | 1 | 3 |
| 存储 | 15MB | 50MB |
| 每月消息 | 100 | 5,000 |
| 预估知识库页数 | 10,000 | 25,000 |
| 公开链接 | 是 | 是 |
| 网站嵌入 | 否 | 是 |
| API 密钥 | 否 | 是 |
| 平台集成 | 否 | 是 |
| 移除品牌 | 否 | 是 |
| 自动同步 | 否 | 是 |
| 高级分析 | 否 | 是 |
Pro 付费功能
- API 密钥：通过 REST API 进行安全密钥认证的程序化访问。
- 移除品牌：隐藏嵌入组件中的「Powered by Kodda」标识。
- 自定义速率限制：配置按助手的请求频率限制。
- 集成：连接 Slack、Discord、Zapier 等平台。
导入规格
支持的文件类型
.PDF.DOCX.DOC.TXT.MD.CSV.JSON.XLSX.HTML.HTM.PPTX
硬性限制
- 单个文件最大：15MB。
- 工作空间存储配额按方案执行。
- 每个助手的内容块数量限制强制执行。
上传验证包括 MIME 类型检查和内容签名检查（如 PDF 文件头、Office zip 签名、JSON 解析验证和文本-二进制安全检查）。
聊天 API 合约
端点：POST /api/chat
- 私有助手：传递
x-api-key请求头（Pro 方案）。 - 已发布的公开助手：请求无需认证（会话保护）。
- 同时支持单条
message和完整的messages数组用于对话历史。
使用消息数组的请求（推荐）
request-with-messages.sh
curl -X POST https://kodda.dev/api/chat \
-H "Content-Type: application/json" \
-H "x-api-key: YOUR_API_KEY" \
-d '{
"botId": "BOT_ID",
"messages": [
{ "role": "user", "content": "Hi, who are you?" },
{ "role": "assistant", "content": "I am your AI assistant." },
{ "role": "user", "content": "Summarize refund policy" }
],
"stream": false
}'使用单条消息的请求
request-single-message.sh
curl -X POST https://kodda.dev/api/chat \
-H "Content-Type: application/json" \
-H "x-api-key: YOUR_API_KEY" \
-d '{
"botId": "BOT_ID",
"message": "Summarize refund policy",
"conversationId": "optional_existing_conversation_id",
"stream": false
}'响应
response.json
{
"answer": "Refunds are accepted within 30 days...",
"sources": [
{ "filename": "policy.pdf", "libraryName": "Product Docs", "score": 0.92, "content": "Relevant snippet..." }
],
"conversationId": "c_123",
"latencyMs": 842
}请求参数
| botId | 必填。要查询的助手 ID。 |
| message | 单条消息字符串（使用此字段或 messages）。 |
| messages | { role, content } 对象数组，用于对话历史。最后一条消息必须来自用户。 |
| conversationId | 选填。继续已有对话。如提供 messages 则忽略。 |
| stream | 布尔值。默认 false。为 true 时返回 SSE 事件。 |
流式模式（stream=true）发送 SSE 事件：sources、token、done 和 error。
API 参考手册
认证方式
在 x-api-key 请求头或 Authorization Bearer 请求头中传递您的 API 密钥。API 密钥在 STARTER 及以上方案可用。
curl -H "x-api-key: kodda_xxxxxxxx" \
-H "Content-Type: application/json" \
-X POST https://kodda.dev/api/chat \
-d '{"botId": "...", "message": "..."}'响应规范
| 2xx | Success — JSON payload |
| 4xx | Validation or auth failure — { error: string } |
| 5xx | Server error — { error: string } |
API 参考手册 — 在线调试
直接在浏览器中测试任意接口。输入您的 API 密钥，填写参数，点击发送请求。代码示例会自动生成 cURL、JavaScript 和 Python 三种格式。
/chat
/feedback
安全与防护
- 方案限制在助手、知识库、文档和聊天配额中由服务端强制执行。
- 聊天用量采用原子递增，生成失败时自动回滚。
- API 密钥在请求执行前通过安全哈希查找验证。
- 配置后，CORS 白名单对已发布的助手强制执行。
- RevenueCat Webhook 同步作为账单权益的真实来源。
需要帮助？请联系 support@kodda.dev。