宝软数字 · FAQ知识库 · 2025-09-15
这篇文章写给技术团队的开发者。如果你需要在现有系统中集成EIOS的能力——比如在你的OA系统里嵌入一个AI助手、或者在数据看板中自动生成文字解读——这篇文章是你的起点。我们从零开始，一步一步走完从获取凭证到成功调用的全过程。
答：EIOS API支持两种认证方式——API Key和OAuth 2.0。
API Key认证（推荐用于服务端调用）：这是最简单的认证方式。登录EIOS管理后台，进入"开发者中心 → API密钥"页面，点击"创建密钥"。你需要给这个密钥命名（如"OA系统集成"）并选择权限范围（只读/读写/管理员）。创建后系统会显示一次完整的密钥字符串——务必复制并安全保存，关闭后不可再次查看。如果密钥泄露，可在后台立即吊销并重新生成。
使用方式：在所有API请求的HTTP头中加入 Authorization: Bearer YOUR_API_KEY。
OAuth 2.0认证（推荐用于前端/客户端调用）：适用场景是第三方应用需要以某个用户身份调用API。支持Authorization Code Grant流程。你需要先在管理后台注册一个OAuth应用，获取Client ID和Client Secret。授权流程为标准OAuth 2.0——引导用户跳转授权页面，用户同意后返回Authorization Code，用Code换取Access Token和Refresh Token。
Access Token有效期2小时，Refresh Token有效期30天。SDK已内置了自动刷新逻辑，你不需要手动处理Token过期问题。
安全建议：API Key永远不要写在前端代码或Git仓库中。对于服务端调用，使用环境变量注入；对于前端调用，用一个轻量级的后端代理层转发请求并注入API Key。
答：以下是Python和TypeScript两个版本的最小可运行示例。
Python版本（使用requests库）：
第一步，安装依赖：pip install requests。
第二步，发送对话请求：
import requests
API_BASE = "https://your-instance.eios.isoftbao.com/api/v1"
API_KEY = "eios_sk_xxxxxxxxxxxxxxxx"
response = requests.post(
f"{API_BASE}/chat/completions",
headers={"Authorization": f"Bearer {API_KEY}","Content-Type": "application/json"},
json={"agent": "general","messages": [{"role": "user","content": "帮我总结一下昨天的销售数据"}]}
)
result = response.json()
print(result["choices"][0]["message"]["content"])
TypeScript版本（使用内置fetch）：
const API_BASE = "https://your-instance.eios.isoftbao.com/api/v1";
const API_KEY = "eios_sk_xxxxxxxxxxxxxxxx";
const response = await fetch(`${API_BASE}/chat/completions`, {
method: "POST",
headers: { "Authorization": `Bearer ${API_KEY}`, "Content-Type": "application/json" },
body: JSON.stringify({ agent: "general", messages: [{ role: "user", content: "帮我总结一下昨天的销售数据" }] }),
});
const result = await response.json();
console.log(result.choices[0].message.content);
响应格式是标准的Chat Completion格式（兼容OpenAI API格式），包含 choices[0].message.content 作为AI回复文本。同时我们还返回了 usage 对象（Token用量统计）和 sources 数组（引用来源，如果Agent使用了知识库的话）。
答：EIOS API按功能分为四组。以下是核心端点速览：
对话与Agent端点：
POST /api/v1/chat/completions —— 发送对话请求，获得AI回复（支持流式响应，设置 stream: true 即可获得SSE流）；
GET /api/v1/agents —— 获取当前可用的Agent列表及各自的描述和能力范围；
POST /api/v1/agents/{agent_id}/execute —— 直接调用指定Agent执行特定任务（非对话模式，适合自动化工作流）。
知识库端点：
POST /api/v1/knowledge/documents —— 上传文档到知识库（支持PDF、Word、Excel、Markdown、TXT）；
GET /api/v1/knowledge/documents —— 列出知识库中的所有文档及索引状态；
DELETE /api/v1/knowledge/documents/{id} —— 删除指定文档及其向量索引。
连接器端点：
GET /api/v1/connectors —— 列出已配置的连接器及连接状态；
POST /api/v1/connectors/{id}/query —— 通过连接器执行数据查询（语言会被转换为对应的SQL或API调用）。
管理端点：
GET /api/v1/usage —— 查询API使用量统计（调用次数、Token消耗、按Agent维度的分布）；
GET /api/v1/audit-logs —— 查询审计日志（支持按时间、用户、操作类型过滤）。
完整的API参考文档部署在你专属的开发者门户上：https://your-instance.eios.isoftbao.com/docs。这份文档包含所有端点的请求/响应示例、参数说明、错误码列表和Rate Limit信息。
答：流式响应是提升用户体验的重要方式。用户不需要等待AI完整生成回复，而是像ChatGPT那样逐字出现。EIOS使用标准的Server-Sent Events协议实现流式响应。
请求时在JSON body中添加 "stream": true 即可开启SSE模式：
response = requests.post(
f"{API_BASE}/chat/completions",
headers={"Authorization": f"Bearer {API_KEY}"},
json={"agent": "general","messages": [{"role": "user","content": "请用500字介绍企业数字化转型"}],"stream": True}, stream=True
)
for line in response.iter_lines():
if line: print(line.decode('utf-8'))
每条SSE事件格式为：data: {"choices":[{"delta":{"content":"新生成"}}]}。最后一条事件包含 finish_reason: "stop" 表示生成完成。
在TypeScript前端中，可以直接使用EventSource或fetch+ReadableStream来处理。我们的前端SDK（@isoftbao/eios-client）已经封装了流式处理的全部细节，你只需传入回调函数即可。
对于更复杂的场景（如需要中断生成、修改正在生成的文本、或实现分支对话），我们推荐使用WebSocket协议。WebSocket端点 wss://your-instance.eios.isoftbao.com/api/v1/ws/chat 支持双向实时通信——你可以随时发送"停止生成"指令，或在不中断连接的情况下切换话题。这在构建类似IDE的AI辅助编程界面或多轮交互式分析仪表盘时特别有用。WebSocket连接每5分钟发送一次心跳包(ping/pong)，如果客户端30秒内未响应心跳，服务端自动断开连接并释放资源。
流式响应中的特殊事件类型也值得一提：除了标准的文本增量事件(delta)外，SSE流中还会包含引用来源事件(source，当AI引用知识库中的某篇文档时触发)、工具调用事件(tool_call，当Agent开始调用外部工具如ERP查询时触发)、以及步骤完成事件(step_done，当多步骤任务完成其中一步时触发)。前端可以利用这些事件类型在UI上展示更丰富的状态——如"正在查询ERP库存数据..."或"已参考《2025年销售管理制度.pdf》第3.2条"。这使得用户不仅能得到答案，还能了解AI的工作过程。
答：我们提供了两套官方SDK，覆盖最常用的开发语言：
Python SDK（pip install eios-client）：完整功能覆盖，包括同步和异步（asyncio）两种调用模式。内置了自动重试、指数退避、连接池管理。支持Pydantic模型类型校验。如果你在做数据管道、定时任务、后端集成，Python SDK是首选。
TypeScript/JavaScript SDK（npm install @isoftbao/eios-client）：完整TypeScript类型定义，享受IDE的智能补全和编译时类型检查。内置了流式响应处理、文件上传进度回调、WebSocket实时通知。如果你的技术栈是Node.js或现代前端框架（React/Vue/Next.js），用这个。
对于其他语言（Java、Go、C#、PHP），你可以直接调用REST API——我们的API设计遵循OpenAPI 3.1规范，提供了完整的JSON Schema定义。你可以使用对应语言的OpenAPI代码生成工具（如openapi-generator）自动生成客户端代码。我们也在Github上维护了一个社区SDK列表，收录了社区贡献的Java SDK和Go SDK。
在实际项目中，我们观察到最常见的集成模式有三种。第一种是后端嵌入——在Node.js或Python后端服务中通过SDK调用EIOS，将AI能力封装成内部微服务，前端通过自己的API网关访问。这种模式的优点是你可以完全控制用户认证、请求限流和结果缓存。第二种是前端直连——在前端（React/Vue）中使用TypeScript SDK直接调用EIOS，适合需要实时流式响应的交互场景（如AI对话界面）。这种模式需要配合一个轻量级的后端代理来隐藏API Key（绝不能在前端代码中暴露Key）。第三种是低代码/无代码集成——通过Webhook和Zapier/Make等自动化平台，将EIOS的AI能力嵌入到已有的工作流中，比如"收到客服邮件→EIOS分析意图→自动分类并指派→回复草稿建议"。这种模式不需要写代码，适合业务团队自助配置。
无论采用哪种集成模式，我们都建议在项目中尽早引入Prompt版本管理的概念。将Agent的系统提示词和关键业务规则放在代码仓库中（而非管理后台手动输入），纳入Git版本控制。这样每次Prompt调整都有迹可循，出了问题可以快速回滚到上一个可用的版本，新同事也能从Git历史中理解Prompt的演进过程。
最快的开发路径：TypeScript/Node.js项目直接用@isoftbao/eios-client，Python后端项目用eios-client，其他语言用OpenAPI Generator一键生成客户端代码。从一个空的Editor到发出第一个成功调用，通常在10分钟内。
答：我们尽量让错误信息足够清晰，让你不需要翻文档就能定位问题。
所有API错误响应遵循统一格式：
{"error": {"code": "INVALID_API_KEY","message": "API Key无效或已过期","details": {"key_prefix": "eios_sk_a1b2","expired_at": "2025-09-15T00:00:00Z"}},"request_id": "req_abc123"}
关键字段：error.code 是机器可读的错误码（可用于程序化处理），error.message 是人类可读的中文错误描述，request_id 是本次请求的唯一标识（联系技术支持时需要提供）。
常见错误及解决方案：
INVALID_API_KEY —— API Key错误或已过期。检查Key格式（应以eios_sk_开头），在管理后台确认Key未被吊销。如果是环境变量问题，检查是否正确加载。
RATE_LIMIT_EXCEEDED —— 请求频率超过限制。默认限制为每分钟60次请求（标准版）或300次（专业版）。可以在响应头的 X-RateLimit-Reset 中看到重置时间。建议实现请求队列和指数退避。
AGENT_NOT_FOUND —— 指定的Agent不存在或无权限访问。用 GET /api/v1/agents 查看可用Agent列表。
CONTEXT_TOO_LONG —— 对话上下文超过模型最大Token限制。需要截断或总结历史消息。我们的SDK已内置了自动摘要策略。
CONNECTOR_ERROR —— 连接器（ERP/CRM等）调用失败。检查error.details中的源系统错误信息，确认源系统是否正常运行、连接参数是否变更。
所有错误都记录了完整的请求上下文（user_id, agent_id, 时间戳, IP地址），可在管理后台的"审计日志"模块中查看详细的错误诊断信息。
除了标准的错误码体系，我们还提供了几个实用的调试工具：
请求回放功能：在管理后台的"API日志"中，每一条请求都附带了完整的请求体（自动脱敏敏感字段）。你可以点击"回放"按钮，系统会用相同的参数重新发送请求——这在复现问题或验证修复时非常有用。回放请求不会真正执行业务操作（如发送邮件、写入数据库），只会返回模拟的响应结果，确保回放不会产生副作用。
响应时间分析：每次API调用的完整响应时间被拆分为四个阶段——网络传输时间、排队等待时间、模型推理时间、后处理时间。如果某次调用特别慢，你可以一眼看出瓶颈在哪个环节。比如网络传输超过2秒，可能是你的网络环境问题；模型推理超过5秒，可能是并发请求太多导致GPU排队。
Token用量预估：在真正调用API之前，你可以使用 POST /api/v1/chat/token-count 端点来预估特定Prompt会消耗多少Token。这在你需要控制成本或避免超出模型上下文窗口时非常有用。端点的响应中会给出预估的输入Token数，以及基于历史数据估算的输出Token范围。
Webhook事件通知：除了通过轮询检查状态外，你还可以配置Webhook来接收异步事件的实时通知。当长时间运行的Agent任务完成时、当知识库文档索引完成时、当月度用量达到预警阈值时，系统会向你配置的URL发送POST请求。Webhook签名使用HMAC-SHA256，你可以验证事件来源的合法性。通过Webhook，你可以构建出完整的事件驱动集成架构，而不是依赖定时轮询。
我们的API采用语义化版本管理。当前稳定版本为v1。API路径中包含版本号（如 /api/v1/chat/completions），这意味着当v2发布时，v1仍然可用。我们承诺每个大版本的生命周期至少为24个月，期间会继续修Bug和安全补丁。大版本切换前至少提前6个月发布迁移指南，包含废弃字段列表、新字段说明、代码迁移示例。
在API响应中，我们会通过响应头 X-API-Version: v1 和 X-API-Deprecated: false 明确告知当前版本状态。如果某个端点或字段即将废弃，响应头中会出现 X-API-Deprecated: true 和 X-API-Sunset: 2025-09-15T00:00:00Z（废弃日期）。建议在CI/CD流程中监控这些响应头，当出现废弃警告时自动通知开发团队。
我们还维护了一份完整的API Changelog，记录每个版本的新增端点、修改的字段、修复的Bug和破坏性变更。Changelog同时发布在开发者门户和NPM/PyPI的Release Notes中。
