cohere-api

cohere-api

目的

此技能集成 Cohere API，用于处理生成嵌入、实现检索增强生成（RAG）、重新排序结果和执行语义搜索等 AI 任务。它旨在通过实时 API 调用，高效处理任务，利用 Cohere 的语言模型增强 AI 工作流。

适用场景

在 ML 流水线中处理文本以生成向量嵌入、构建 RAG 系统以准确响应查询、重新排序搜索结果以提升相关性，或对大型数据集进行语义搜索时，可使用此技能。在需要通过 API 增强 AI 的场景中使用，例如需要上下文检索的聊天机器人，或分析文本相似度的应用。

主要功能

• 生成嵌入：通过 /embed 端点将文本转换为向量，每次请求最多支持 512 个 token，支持 "embed-english-v3.0" 等模型。
• 实现 RAG：使用外部数据源通过 /generate 获取并增强响应，输入和输出最多可处理 2048 个 token。
• 重新排序：使用 /rerank 端点根据查询相关性为文本列表评分并重新排序，可选择 top-k 结果。
• 语义搜索：利用嵌入执行相似度搜索，并与 Pinecone 或 Weaviate 等向量数据库集成。
• 速率限制：API 限制为每分钟 60 次请求；可通过响应标头监控用量。
• 模型选择：在请求中指定模型，例如用于生成的 "command" 或用于跨语言嵌入的 "embed-multilingual-v2.0"。

使用模式

使用此技能时，首先设置用于身份验证的环境变量：export COHERE_API_KEY=your_api_key。然后，通过 HTTP 请求或 Cohere SDK 发起 API 调用。生成嵌入时，使用包含文本数组的 JSON 负载构造请求。在 RAG 模式中，先检索文档，再将其传递给 /generate，以获取具备上下文感知能力的响应。始终通过检查响应状态码来处理异步模式。重新排序时，通过一次调用将搜索结果传递给端点。在代码中使用 try-except 块包装 API 交互，以提高可靠性。

常用命令/API

使用 curl 或 Python SDK 与 Cohere API 端点交互。身份验证需要使用 $COHERE_API_KEY 中的 Bearer 令牌。

• 嵌入端点：POST https://api.cohere.ai/v1/embed 示例：curl -X POST https://api.cohere.ai/v1/embed -H "Authorization: Bearer $COHERE_API_KEY" -H "Content-Type: application/json" -d '{"texts": ["Hello world"], "model": "embed-english-v3.0"}'

• 生成端点（用于 RAG）：POST https://api.cohere.ai/v1/generate 代码片段： import cohere; import os client = cohere.Client(api_key=os.environ['COHERE_API_KEY']) response = client.generate(model='command', prompt='Explain AI', max_tokens=50)

• 重新排序端点：POST https://api.cohere.ai/v1/rerank 示例：curl -X POST https://api.cohere.ai/v1/rerank -H "Authorization: Bearer $COHERE_API_KEY" -d '{"query": "best AI tools", "documents": ["OpenClaw is great", "Cohere is useful"], "top_n": 1}'

• 语义搜索模式：先生成嵌入，然后在代码中计算余弦相似度。 代码片段： import numpy as np emb1 = response.body['embeddings'][0] # From embed response emb2 = [0.1, 0.2, ...] # Another embedding similarity = np.dot(emb1, emb2) / (np.linalg.norm(emb1) * np.linalg.norm(emb2))

配置格式：所有请求均使用 JSON；使用 SDK 时，传入 {"model": "command", "prompt": "text"} 这类字典。

集成说明

在 Python 环境中导入 Cohere SDK 以完成集成：pip install cohere。将 $COHERE_API_KEY 设置为环境变量，以便安全地进行处理。在 OpenClaw 工作流中，通过函数调用使用此技能，例如在 Agent 提示词中使用技能 ID "cohere-api"。对于多步集成，可串联输出：将一次调用生成的嵌入用作 RAG 的输入。通过 Cohere 控制面板监控 API 用量，以避免触发速率限制。确保所有请求均使用 HTTPS，并在需要时处理区域端点（例如 us.cohere.ai）。

错误处理

常见错误包括 401 Unauthorized（缺少或无效的 API 密钥）、429 Too Many Requests（超出速率限制）和 400 Bad Request（JSON 或参数无效）。处理方法：在代码中检查 response.status_code，并对 429 错误使用指数退避重试。对于 401，验证 $COHERE_API_KEY 并记录问题。使用如下 try-except 代码块： 代码片段： try: response = client.embed(texts=["text"]) except cohere.CohereError as e: if e.http_status == 429: time.sleep(60) # Wait and retry else: raise 始终在调用 API 前验证输入，以避免 400 错误，例如确保文本长度少于 512 个令牌。

具体用法示例

示例 1：生成用于语义搜索的嵌入 为查询生成嵌入并与文档进行比较： 首先，进行设置：export COHERE_API_KEY=your_key 然后，运行： import cohere; import os client = cohere.Client(api_key=os.environ['COHERE_API_KEY']) emb_response = client.embed(texts=["What is AI?"]) query_emb = emb_response.body['embeddings'][0]

Use query_emb for similarity search in a vector DB

示例 2：实现用于问答的 RAG 使用 RAG 时，检索上下文并生成回答： 准备文档数组，例如：docs = ["AI is machine intelligence."] 代码： response = client.generate( model='command', prompt='What is AI? Context: ' + ' '.join(docs), max_tokens=100 ) print(response.body['generations'][0]['text']) # Output the generated answer

图关系

• 关联集群：ai-apis（例如，与 openai-api 等其他基于 API 的技能共享依赖项）。
• 通过标签连接：ai-apis、api（链接到类似类别中的技能，以支持组合工作流）。
• 输出：为 vector-stores 等技能提供输入，以执行基于嵌入的搜索。