SuperAPI AI 工具集
合作ENAI 行业资讯收藏
Skill 广场telnyx-ai-inference-ruby

telnyx-ai-inference-ruby

智能体与模型

查看项目

更新于 10-16 03:56

技能介绍

用途

该技能面向 Ruby 开发者，用于访问 Telnyx 的 LLM 推理 API、嵌入（embeddings）以及通话洞察与摘要等 AI 分析能力。技能以 Ruby SDK 示例的形式给出，所有示例都假定已按统一方式初始化客户端。

安装与初始化

安装命令：

gem install telnyx

初始化示例：

require "telnyx"

client = Telnyx::Client.new( api_key: ENV["TELNYX_API_KEY"], # This is the default and can be omitted )

文档说明，后续所有示例均假定 client 已按上述方式初始化。

错误处理

文档指出所有 API 调用都可能因网络错误、限流（429）、校验错误（422）或认证错误（401）而失败，并建议在生产代码中始终处理错误。示例展示了分别捕获 Telnyx::Errors::APIConnectionError、Telnyx::Errors::RateLimitError、Telnyx::Errors::APIStatusError 的处理方式。其中 429 限流建议等待并使用指数退避重试，并提示可检查 Retry-After 头获取实际延迟。常见错误码包括：401 无效 API key、403 权限不足、404 资源未找到、422 校验错误（检查字段格式）、429 限流（使用指数退避重试）。

分页

文档提示分页可使用 .auto_paging_each 进行自动迭代，示例：page.auto_paging_each { |item| puts item.id }。

语音转文字

POST /ai/audio/transcriptions，用于将语音转写为文本。该端点与 OpenAI Transcription API 一致，可与 OpenAI 的 JS 或 Python SDK 配合使用。示例：

response = client.ai.audio.transcribe(model: :"distil-whisper/distil-large-v2")

返回字段：duration（number）、segments（array[object]）、text（string）、words（array[object]）。

聊天补全

POST /ai/chat/completions，必填参数 messages。文档标注该端点已废弃，建议改用 POST /v2/ai/openai/chat/completions。该端点与 OpenAI Chat Completions API 一致，可与 OpenAI 的 JS 或 Python SDK 配合使用。可选参数包括 api_key_ref、best_of、early_stopping、enable_thinking、frequency_penalty、guided_choice、guided_json、guided_regex、length_penalty、logprobs、max_tokens、min_p、model、n、presence_penalty、response_format、seed、stop、stream、temperature、tool_choice（枚举：none、auto、required）、tools、top_logprobs、top_p、use_beam_search。

会话（Conversations）管理

  • 列出会话：GET /ai/conversations，支持 PostgREST 风格的查询参数用于过滤，可对 metadata JSON 对象中的任意字段进行过滤。返回字段：created_at、id、last_message_at、metadata、name。
  • 创建会话：POST /ai/conversations，可选参数 metadata、name。
  • 获取会话：GET /ai/conversations/{conversation_id}。
  • 更新会话元数据：PUT /ai/conversations/{conversation_id}，可选参数 metadata。
  • 删除会话：DELETE /ai/conversations/{conversation_id}。
  • 获取会话洞察：GET /ai/conversations/{conversation_id}/conversations-insights，返回 conversation_insights（array[object]）、created_at、id、status（枚举：pending、in_progress、completed、failed）。
  • 创建消息：POST /ai/conversations/{conversation_id}/message，必填 role，可选 content、metadata、name、sent_at、tool_call_id、tool_calls、tool_choice。用于在不使用 chat 端点的情况下手动向会话插入新消息。
  • 获取会话消息：GET /ai/conversations/{conversation_id}/messages，返回包含助手发起的工具调用的信息，字段包括 created_at、role（枚举：user、assistant、tool）、sent_at、text、tool_calls。

洞察模板与分组

  • 聚合会话洞察：GET /ai/conversations/conversation-insights/aggregates，按指定字段聚合，返回 record_count。
  • 获取洞察分组：GET /ai/conversations/insight-groups。
  • 创建洞察分组：POST /ai/conversations/insight-groups，必填 name，可选 description、webhook。
  • 获取单个洞察分组：GET /ai/conversations/insight-groups/{group_id}。
  • 更新洞察分组：PUT /ai/conversations/insight-groups/{group_id}，可选 description、name、webhook。
  • 删除洞察分组：DELETE /ai/conversations/insight-groups/{group_id}。
  • 将洞察模板分配到分组：POST /ai/conversations/insight-groups/{group_id}/insights/{insight_id}/assign。
  • 从分组移除洞察模板：DELETE /ai/conversations/insight-groups/{group_id}/insights/{insight_id}/unassign。
  • 获取洞察模板列表：GET /ai/conversations/insights，返回 created_at、id、insight_type（枚举：custom、default）、instructions、json_schema、name、webhook。
  • 创建洞察模板：POST /ai/conversations/insights，必填 instructions、name，可选 json_schema、webhook。
  • 获取单个洞察模板：GET /ai/conversations/insights/{insight_id}。
  • 更新洞察模板：PUT /ai/conversations/insights/{insight_id}，可选 instructions、json_schema、name、webhook。
  • 删除洞察模板：DELETE /ai/conversations/insights/{insight_id}。

嵌入（Embeddings）

  • 按状态获取任务：GET /ai/embeddings，返回用户处于 queued、processing、failed、success、partial_success 状态的任务，默认显示 queued 和 processing。返回字段：bucket、created_at、finished_at、status、task_id、task_name、user_id。
  • 嵌入文档：POST /ai/embeddings，必填 bucket_name，可选 document_chunk_overlap_size、document_chunk_size、embedding_model、loader。在 Telnyx Storage Bucket 上使用嵌入模型执行嵌入。当前支持的文件类型：PDF、HTML、txt/非结构化文本、json、csv、音频/视频（mp3、mp4、mpeg、mpga、m4a、wav 或 webm，最大 100mb 文件大小）。不匹配以上类型的文件将尝试作为非结构化文本嵌入。
  • 列出已嵌入的存储桶：GET /ai/embeddings/buckets，返回 buckets（array[string]）。
  • 获取存储桶内文件级嵌入状态：GET /ai/embeddings/buckets/{bucket_name}，返回 created_at、error_reason、filename、last_embedded_at、status、updated_at。
  • 禁用某个已嵌入存储桶的 AI：DELETE /ai/embeddings/buckets/{bucket_name}。删除整个存储桶的嵌入并禁用该存储桶的 AI 用途，使其恢复为普通存储定价。
  • 相似度搜索：POST /ai/embeddings/similarity-search，必填 bucket_name、query，可选 num_of_docs。在 Telnyx Storage Bucket 上执行相似度搜索，返回与查询最相似的 num_docs 个文档分块。当前唯一可用的距离度量为余弦相似度，返回 0 到 1 之间的距离，距离越小表示与查询越相似。返回字段：distance、document_chunk、metadata。
  • 嵌入 URL 内容：POST /ai/embeddings/url，必填 url、bucket_name。嵌入指定 URL 的网站内容，并抓取同一域名下最多 5 层的子页面，将内容加载到 Telnyx Cloud Storage 存储桶。
  • 获取嵌入任务状态：GET /ai/embeddings/{task_id}。状态说明：queued（等待工作进程取走任务）、processing（嵌入任务运行中）、success（任务成功完成且存储桶已嵌入）、failure（任务失败且没有文件成功嵌入）、partial_success（部分文件成功嵌入，但至少有一个失败）。

微调（Fine Tuning）

  • 列出微调任务：GET /ai/fine_tuning/jobs，返回 created_at、finished_at、hyperparameters、id、model、organization_id、status（枚举：queued、running、succeeded、failed、cancelled）、trained_tokens、training_file。
  • 创建微调任务：POST /ai/fine_tuning/jobs，必填 model、training_file，可选 hyperparameters、suffix。示例使用模型 openai/gpt-4o 与训练文件 training-data.jsonl。
  • 获取微调任务：GET /ai/fine_tuning/jobs/{job_id}。
  • 取消微调任务：POST /ai/fine_tuning/jobs/{job_id}/cancel。

适用场景与限制

该技能适合需要在 Ruby 中集成 Telnyx 通信侧 AI 能力的场景，例如语音转写、聊天补全、会话及洞察管理、文档嵌入与相似度检索、URL 内容嵌入、微调任务管理等。文档中关于收费、价格、具体平台限制等信息暂未提供。