如何通过tweepy访问Twitter API v2的tweet annotations接口

• 不需要单独调用专属端点，Tweepy v4.0及以上版本原生支持获取Tweet Annotations自动分类结果。

Twitter API v2的推文标注能力不是独立部署的单独端点，是所有返回推文对象的接口都内置的扩展字段，只要在请求时显式声明要拉取对应字段，就能拿到分类结果，不需要额外封装请求。

具体实现方法 #

调用任意Tweepy v2的推文相关接口（包括近期推文搜索、全量历史搜索、单条推文查询、用户时间线拉取、过滤流实时拉取等）时，在tweet_fields参数中加入context_annotations和entities两个值，返回的推文对象中就会携带标注数据。

参考代码示例：

import tweepy

# 初始化API v2客户端，替换为你自己的Bearer Token
client = tweepy.Client(bearer_token="你的Bearer Token")

# 以搜索最近7天推文为例
tweet_resp = client.search_recent_tweets(
    query="搜索关键词",
    # 关键：显式声明需要返回标注相关的推文字段
    tweet_fields=["context_annotations", "entities"],
    max_results=20
)

for tweet in tweet_resp.data:
    print(f"\n推文内容：{tweet.text}")
    # 读取推文整体维度的上下文分类标注
    if tweet.context_annotations:
        print("* 整体上下文分类：")
        for anno in tweet.context_annotations:
            print(f"  领域：{anno.domain.name}，实体：{anno.entity.name}")
    # 读取词汇级别的实体自动分类结果
    if tweet.entities and "annotations" in tweet.entities:
        print("* 词汇级分类标注：")
        for word_anno in tweet.entities["annotations"]:
            print(f"  匹配词汇：{word_anno.normalized_text}，分类：{word_anno.type}，置信度：{word_anno.probability}")

两类标注的区别 #

• context_annotations：推文整体层面的语义分类，会识别推文所属的话题领域、关联的公共实体（比如公众人物、品牌、赛事、影视作品等），适合做推文整体的内容归类。
• entities.annotations：词汇粒度的自动分类结果，会定位推文中出现的特定词汇，标注其所属分类（人物、地点、组织、产品等）、归一化实体名、模型识别置信度，以及该词汇在推文中的起止位置。

常见踩坑说明 #

• 如果返回结果里找不到标注字段，先检查是否在tweet_fields里声明了对应字段：Twitter API v2默认只返回推文id、文本两个基础字段，所有扩展字段都必须显式请求才会返回。
• 请使用4.0及以上版本的Tweepy，低版本对v2接口的字段支持不全，可能出现标注字段无法解析的问题，升级可以直接执行pip install --upgrade tweepy。
• 实时流接口获取标注的逻辑和搜索接口完全一致，只要在建立流连接时传入对应的tweet_fields参数即可，不需要额外配置。

内容的提问来源于stack exchange，提问作者Infomagier