查询 SDK（Python 与 Go）

使用 Consumer API Key 查询数据。没有 Key 时，先在 Portal 申请应用订阅与密钥。下载不需要管理员登录；API 调用仍受应用权限约束。

Python

需要 Python 3.10 或更新版本：

Bash

curl -fsSL https://www.marsyoo.com/api/sdk/python-consumer \
  -o marsyoo-python-consumer-sdk-v0.2.0.tar.gz
tar -xzf marsyoo-python-consumer-sdk-v0.2.0.tar.gz
cd marsyoo-python-consumer-sdk-v0.2.0
python3 -m venv .venv
. .venv/bin/activate
python -m pip install .

将应用密钥放入 WHALE_API_KEY 环境变量，再执行：

Python

import os
from whale_consumer import Client
 
client = Client(api_key=os.environ["WHALE_API_KEY"], timeout=30)
result = client.search(query="人工智能", mode="keyword", limit=10)
for item in result.get("results", []):
    document_id = item["document_id"]
    content = client.get_document_content(document_id)
    print(document_id, content.get("content", {}).get("body", ""))

results=[] 表示本次没有匹配结果，不会自动采集。当前 Python 包只提供消费 API，不包含采集器模块。

Go

下载 Go Consumer SDK，解压并在包目录运行 go test ./...。在你的 Go 应用中使用本地模块路径：

Bash

go mod edit -require=whale/sdk/go/consumer@v0.0.0
go mod edit -replace=whale/sdk/go/consumer=/absolute/path/to/marsyoo-go-consumer-sdk-v0.2.0

将解压路径替换为实际绝对路径。模块的 README 包含查询与变化订阅示例；导入路径为 whale/sdk/go/consumer。

以下示例可放入应用的 main.go：

package main
 
import (
    "context"
    "fmt"
    "log"
    "os"
    "time"
 
    consumer "whale/sdk/go/consumer"
)
 
func main() {
    key := os.Getenv("WHALE_API_KEY")
    if key == "" {
        log.Fatal("Set WHALE_API_KEY")
    }
    ctx, cancel := context.WithTimeout(context.Background(), 30*time.Second)
    defer cancel()
    client := consumer.New("https://www.marsyoo.com", key)
    result, err := client.Search(ctx, consumer.SearchRequest{Query: "AI", Mode: "keyword", Limit: 10})
    if err != nil {
        log.Fatal(err)
    }
    for _, item := range result.Results {
        content, err := client.GetDocumentContent(ctx, item.DocumentID, "")
        if err != nil {
            log.Fatal(err)
        }
        fmt.Println(item.DocumentID, content.Content["body"])
    }
}

加入代码后执行 go mod tidy，再执行 go run .。没有匹配结果时不会请求正文接口。

按话题或分类获取内容

Python

page = client.browse_documents(
    dataset_id="social_media_raw",
    topics=["AI"],
    created_from="2026-10-01T00:00:00Z",
    created_to="2026-10-02T00:00:00Z",
    limit=50,
)
for item in page.get("documents", []):
    print(item["document"]["id"])

后续页保持参数不变，并传入返回的 next_cursor 为 cursor。Python 还提供 get_user、list_user_documents、list_classifications、search_history；Go 对应 GetUser、ListUserDocuments、ListClassifications、SearchHistory、BrowseDocuments 与 CatalogRequest。检索可传 query_vector / QueryVector；检索 cursor / Cursor 仅限 keyword 模式。用户资料是已有采集观察，不是实时平台用户档案。

方法一览

用途	Python	Go	对应接口
检索	`search`	`Search`	`POST /v1/search`
历史检索	`search_history`	`SearchHistory`	`POST /v1/search/history`
按条件筛选内容	`browse_documents`	`BrowseDocuments`	`GET /v1/documents/browse`
读取用户资料	`get_user`	`GetUser`	`GET /v1/users/{platform}/{id}`
读取用户的内容	`list_user_documents`	`ListUserDocuments`	`GET /v1/users/{platform}/{id}/documents`
查询分类字典	`list_classifications`	`ListClassifications`	`GET /v1/classifications`
读取文档元数据	`get_document`	`GetDocument`	`GET /v1/documents/{id}`
读取完整正文	`get_document_content`	`GetDocumentContent`	`GET /v1/documents/{id}/content`
批量读取	`batch_get`	`BatchGet`	`POST /v1/documents/batch-get`
正文版本历史	`list_document_versions`	`ListDocumentVersions`	`GET /v1/documents/{id}/versions`
指标快照历史	`list_document_snapshots`	`ListDocumentSnapshots`	`GET /v1/documents/{id}/snapshots`
字幕、OCR 等片段	`list_document_parts`	`ListDocumentParts`	`GET /v1/documents/{id}/parts`
结构化事实	`list_document_facts`	`ListDocumentFacts`	`GET /v1/documents/{id}/facts`
附件列表与下载链接	`list_attachments`、`get_attachment_download_url`	`ListAttachments`、`GetAttachmentDownloadURL`	`GET /v1/documents/{id}/attachments…`
增量同步	`list_changes`、`iter_change_pages`	`ListChanges`、`NewChangesIterator`	`GET /v1/changes`
按需采集	`create_live_query`、`get_live_query`、`list_live_query_results`、`cancel_live_query`	`CreateLiveQuery`、`GetLiveQuery`、`ListLiveQueryResults`、`CancelLiveQuery`	`/v1/live-queries…`
定期采集	`create_collection_subscription`、`list_collection_subscriptions`、`pause_…`/`resume_collection_subscription`、`list_collection_subscription_tasks`	`CreateCollectionSubscription`、`ListCollectionSubscriptions`、`Pause…`/`ResumeCollectionSubscription`、`ListCollectionSubscriptionTasks`	`/v1/collection/subscriptions…`
批量导出	`create_export`、`get_export`、`list_export_files`、`download_export_file`、`cancel_export`	`CreateExport`、`GetExport`、`ListExportFiles`、`DownloadExportFile`、`CancelExport`	`/v1/exports…`
分析任务（Preview）	`create_analysis_run`、`get_analysis_run`、`cancel_analysis_run`、`list_analysis_artifacts`、`download_analysis_artifact`，以及 `_analysis_subscription`、`get_analysis_checkpoint`	`CreateAnalysisRun`、`GetAnalysisRun`、`CancelAnalysisRun`、`ListAnalysisArtifacts`、`DownloadAnalysisArtifact`，以及 `AnalysisSubscription`、`GetAnalysisCheckpoint`	`/v1/analysis…`

下载文件的方法（download_export_file、download_analysis_artifact 及 Go 对应方法）以流式写入，不会把整个文件读入内存。附件下载链接是 300 秒有效的签名 URL，直接下载，不要携带 API Key。

错误、重试与超时

接口返回非 2xx 时抛出或返回 APIError，包含 code、message 和 HTTP 状态（Python 为 status，Go 为 Status）。错误码含义见限流、重试与排错。
只有增量同步（list_changes / ListChanges 及其迭代器）会在网络错误、429 和 5xx 时自动重试，连同首次最多 3 次，间隔指数递增；其他方法不自动重试，由你按排错页的建议处理。
Python 默认超时 30 秒，可用 Client(timeout=...) 调整；Go 用调用时传入的 context 控制超时和取消。

接下来

关键词与语义检索：平台、时间、语言和字段过滤。
用户、话题、标签与分类：精确筛选、分类 code 与字段权限。
读取内容与历史：正文、版本、片段和事实。
增量同步数据：处理整页后保存游标。
限流、重试与排错：超时、限流和错误处理。

附件下载及 SDK 未封装的接口使用相同 Consumer Key，通过 HTTP API 调用。