Filtro de chat en directo: insultos, spoilers y spam interceptados de una vez
💡 Resumen en una frase: usa Jev para construir una canalización de filtrado de IA para el chat en directo: un mensaje, una solicitud, tres preguntas; 8 hilos concurrentes y reglas de código puro que deciden lo que ve el espectador.
Estás viendo un directo y los mensajes del chat pasan más rápido de lo que puedes leer. El enfoque del Twitch chat filter cookbook oficial: cada mensaje que llega se envía individualmente a Jev en una solicitud, junto con el título del directo y el nombre del juego, con tres preguntas: qué tipo de mensaje es, si es un insulto y si es un spoiler; después, unas reglas simples convierten las respuestas en lo que ve el espectador: las preguntas se destacan; insultos, consejos no solicitados y anuncios se ocultan; los spoilers se censuran.
Una lista de palabras clave puede atrapar enlaces de spam, pero en «go left, there's a site of grace behind the tree» no hay ninguna palabra prohibida, ni tampoco en una revelación de la trama; ahí está la línea divisoria entre el filtro de IA para el chat en directo y una lista negra: el juicio está en la semántica, no en lo literal. La organización oficial lo probó con 29 mensajes de un directo de Elden Ring: ocultó 7, censuró 2 y destacó 6 preguntas, con una mediana de tiempo por solicitud de unos 0.1 segundos. Esta lección te guía para ejecutar todo el conjunto en unos 15 minutos, y sin configurar ninguna API Key también puedes reproducir todas las cifras oficiales: el paso 1 te dará el archivo de caché oficial.
Qué podrás hacer al terminar
- Construir una canalización de filtrado de IA para el chat en directo: un mensaje, una solicitud, tres preguntas;
ThreadPoolExecutor8 hilos concurrentes para procesar todo el chat - Entender la división de trabajo de las tres preguntas:
categoryChoice define la acción por defecto, y las dos preguntas Noultoxic/spoilerse encargan del veto inmediato y de la censura - Convertir las respuestas en acciones con
decide(): cambiar las reglas es solo cambiar código, las 29 respuestas se reutilizan tal cual, 0 nuevas solicitudes - Reproducir las cifras oficiales sin gastar un céntimo: descarga la caché oficial
json_cache.jsony reprodúcela; calibra los umbrales antes de usar tus propios mensajes
Por qué usar Jev y no una lista negra de palabras clave
La lista negra es el estado actual, y un LLM común es el otro extremo. El cookbook oficial señala desde el principio la limitación de la lista negra: las palabras clave pueden atrapar enlaces de spam, pero no spoilers ni consejos sin palabras prohibidas. Comparemos las tres opciones juntas:
| Capacidad | Lista negra de palabras clave | LLM común | Jev |
|---|---|---|---|
| Spoilers/consejos sin palabras ofensivas | ❌ «Detrás del árbol hay una gracia» no contiene ninguna palabra prohibida, pasa inadvertido | ✅ Lo entiende, pero la respuesta es un texto que hay que volver a analizar | ✅ Prueba oficial: consejo no solicitado backseat 1.00, spoiler 0.95, las probabilidades entran directamente en el código |
| El matiz entre broma e insulto | ❌ «you're so bad at this boss» contiene bad, hasta una broma entre amigos sale cortada | ⚠️ Sabe distinguir, pero «cuánta certeza hay» hay que preguntárselo | ✅ Burla en tono de broma toxic 0.28, insulto real 0.97, distinción tajante |
| Rendimiento en horas pico | ✅ Coincidencias rápidas | ❌ Genera respuestas una por una, el chat no lo espera | ✅ Prueba oficial: mediana de solicitud de unos 0.1 segundos, 8 hilos concurrentes |
| Cambiar las reglas | ✅ Cambia la tabla y surte efecto | ❌ Las reglas están escritas en el prompt, cualquier cambio obliga a reejecutar todo | ✅ Las reglas están en decide(), las 29 respuestas se reutilizan, 0 nuevas solicitudes |
| Forma de la respuesta | ✅ Booleana | ❌ Texto libre o JSON, el análisis fallará | ✅ Respuesta tipada + distribución de probabilidades, sin análisis |
Siendo justos: la lista negra debería quedarse; para atrapar enlaces de spam es rápida y barata, y Jev cubre la mitad que ella no ve. No se excluyen mutuamente.
Tu situación actual
- «Tres horas de directo, insultos, spoilers y vendedores de seguidores mezclados en el chat, moderando a mano hasta marearte, la moderación siempre va con retraso»
- «La lista negra de palabras clave solo coincide con lo literal: “Ve a la izquierda, detrás del árbol hay una gracia” no tiene ninguna palabra prohibida y aun así arruina la experiencia del estreno con un spoiler»
- «Quiero usar un LLM para el filtro de comentarios con IA, pero cada mensaje tarda varios segundos en recibir respuesta y en horas pico se acumula sin control; si le pido solo etiquetas, la misma frase da dos respuestas distintas»
Cuándo usar esta técnica
Cuando necesitas:
- Un veredicto inmediato al llegar cada mensaje, sin cortes ni en horas pico
- Interceptar más que palabras ofensivas: spoilers, consejos de juego no solicitados y anuncios, todos juzgados por semántica
- Reglas que cambian en cualquier momento: hoy se ocultan anuncios, el día del partido se ocultan también los vítores, y cambiar reglas no vuelve a costar dinero
Y además no quieres:
- Mantener una tabla de palabras clave que nunca alcanza a las variantes
- Analizar una vez por mensaje el JSON que escupe un LLM
- Juzgar spoilers fuera del contexto del juego: la misma frase significa cosas completamente distintas en juegos diferentes
🎒 Preparativos antes de empezar
- Haber completado Choice, preguntas de selección: saber escribir un map de opciones
criteriay entenderchoiceyprobabilities - Completé Noul sí/no: sé que
noules una probabilidad 0–1, con umbrales iniciales yes ≥ 0.7 / no ≤ 0.3 - Logré ejecutar la instalación y la primera solicitud:
.venvestá disponible (esta página admite la reproducción desde caché, así que por ahora puedes continuar sin Key; véase el paso 1) - Un vaso de agua ☕——esta lección es un mini proyecto completo: 29 mensajes de chat + tres preguntas + un conjunto de código de filtrado que funciona
Hazlo conmigo
Primero aclaremos cómo ejecutarlo: crea un nuevo twitch_chat_filter.py y pega los bloques de código de cada paso en orden en el mismo archivo; ejecuta python twitch_chat_filter.py después de completar cada paso. Las respuestas se guardan en caché, por lo que ejecutarlo repetidamente no genera gastos repetidos.
Paso 1: instalar el entorno, descargar la caché oficial y preparar 29 mensajes de muestra
Por qué: el equipo oficial escribió para este caso un conjunto completo de mensajes de chat muy realistas——un directo de Elden Ring, 29 mensajes, con cada tipo de mensaje apareciendo al menos dos veces (incluidos dos de solo emojis). Lo usamos directamente para validar toda la lógica de filtrado sin esperar a un directo real. El equipo oficial también publicó la caché de respuestas de estos 29 mensajes json_cache.json; si la pones en el lugar correcto, puedes reproducir todas las cifras oficiales sin llamar a la API.
Instala las dependencias. cooksafe es la pequeña librería auxiliar que acompaña al cookbook oficial (su descripción en PyPI dice «Shared helpers for the TypeSafe cookbooks»); en esta página usamos su caché JsonCache y su enlace para compartir make_playground_link:
pip install 'typesafe-sdk>=0.7.1,<0.8.0' ipython 'cooksafe>=0.2.0,<0.3.0'Descarga la caché oficial (enlace directo raw, probado y funcional. También puedes no descargarla——si configuras TYPESAFE_API_KEY serán solicitudes reales; el costo se detalla enmodelos y precios):
curl -sL -o json_cache.json https://raw.githubusercontent.com/typesafe-ai/typesafe-public-examples/main/cookbooks/twitch_chat_filter/json_cache.jsonCrea un nuevo twitch_chat_filter.py y pega el primer bloque de código——el cliente, la caché y los datos de muestra. Observa el valor predeterminado "cache-only" de api_key: sin Key, la reproducción desde caché sigue funcionando con normalidad:
from concurrent.futures import ThreadPoolExecutor
import os
from pathlib import Path
from time import perf_counter
from cooksafe import JsonCache, make_playground_link
from IPython.display import Markdown, display
from typesafe_sdk import Choice, Noul, NoulCriteria, TypeSafeClient
TYPESAFE_MODEL = "jev-1.14.0" # 官方数字的采样版本(2026-10-29)
client = TypeSafeClient(
api_key=os.environ.get("TYPESAFE_API_KEY", "cache-only"), # cached re-renders need no key
base_url=os.environ.get("TYPESAFE_ENDPOINT"),
timeout=60.0,
)
CACHE_DIR = Path(__file__).resolve().parent if "__file__" in globals() else Path.cwd()
json_cache = JsonCache(CACHE_DIR / "json_cache.json")
STREAM = {"title": "Elden Ring first playthrough! No spoilers please", "game": "Elden Ring"}
CHAT = [
("night-owl-22", "hi chat, first time catching a stream live"),
("ggwp-andy", "PogChamp PogChamp PogChamp"),
("mira-plays", "how many hours have you played so far?"),
("tarnished-tom", "this area looks so good at night"),
("backseat-bert", "go left, there's a site of grace behind the tree"),
("follow4follow-bot", "Want more viewers? Buy 1000 followers for $5 at cheapviewz dot example"),
("lore-hound", "wait till you find out Ranni planned the Night of Black Knives"),
("kappa-kev", "LUL LUL LUL"),
("sunny-skies", "are you going to do a no-hit run after this?"),
("rage-ryan", "you're genuinely the worst player i've ever seen, uninstall trash"),
("cozy-cat", "the music in this area is so good"),
("backseat-bert", "use your flask NOW, why are you not healing"),
("mira-plays", "W streamer"),
("ggwp-andy", "GG that was insane"),
("quiet-quinn", "anyone else watching from Brazil?"),
("tarnished-tom", "what build are you going for?"),
("lore-hound", "the ending where you become Elden Lord with Ranni is the best one"),
("kappa-kev", "chat is wild today lol"),
("backseat-bert", "the boss is weak to fire, equip the torch before you go in"),
("rage-ryan", "nobody cares about your opinion, go back to your basement"),
("cozy-cat", "you're so bad at this boss lmao, love you tho"),
("sunny-skies", "who is the final boss?"),
("ggwp-andy", "LETS GOOOO"),
("night-owl-22", "i just got this game too, it's so hard"),
("promo-pete", "check out my channel, I stream every day, follow me!"),
("quiet-quinn", "dodge rolling through that was clean"),
("mira-plays", "is the DLC worth it?"),
("cozy-cat", "your character looks so cool"),
("night-owl-22", "this boss took me 40 tries lol"),
]
print(f"{len(CHAT)} messages. What one request sends as its state:")
print({"stream": STREAM, "message": {"user": CHAT[4][0], "text": CHAT[4][1]}})Ejecuta python twitch_chat_filter.py.
Deberías ver:
29 messages. What one request sends as its state:
{'stream': {'title': 'Elden Ring first playthrough! No spoilers please', 'game': 'Elden Ring'}, 'message': {'user': 'backseat-bert', 'text': "go left, there's a site of grace behind the tree"}}Anota primero dos puntos de diseño. El título del directo y el nombre del juego entran en cada solicitud: si un mensaje es una indicación backseat o un spoiler depende de qué juego se está jugando, así que forman parte del state. Una solicitud por mensaje: los mensajes no dependen entre sí, lo que allana el camino para la concurrencia del paso 5.
- Obtuve las dos líneas de 29 messages;
json_cache.jsonestá justo al lado del script
Paso 2: escribir las tres preguntas: una clasificación Choice más dos Noul
Por qué: cada mensaje de chat requiere juzgar tres cosas——qué es (lo que determina la disposición predeterminada), si es ofensivo (veto inmediato) y si es un spoiler (difuminar). Las tres preguntas se envían en una sola solicitud sobre el mismo state; Jev evalúa en paralelo y de forma independiente, y añadir preguntas casi no aumenta el tiempo de respuesta.
A continuación pega la definición de las preguntas:
QUESTIONS = {
"category": Choice(
instructions="Which category best describes the main purpose of `message.text`?",
criteria={
"question": "A genuine request for information from the streamer or chat, "
"not gameplay instructions phrased as a question or a promotional pitch",
"hype": "Cheering, reactions, or repeated emotes (PogChamp, LUL, GG, W, "
"lets gooo); repetition alone does not make cheering spam",
"conversation": "Ordinary chatter, opinions, replies, useful shared links, "
"or any message whose main purpose does not fit the other categories",
"backseat": "Unrequested gameplay advice telling the streamer what to do, "
"including instructions phrased as a question; not a request for information",
"spam": "Unsolicited advertising, self-promotion, follower selling, or "
"promotional links; not ordinary cheering, repeated emotes, or a useful link",
},
),
"toxic": Noul(
instructions="Is this message insulting, hateful or harassing towards someone?",
criteria=NoulCriteria(
true="Insults, slurs, threats or personal attacks on the streamer or another viewer",
false="Friendly, neutral, or light banter with no target",
),
),
"spoiler": Noul(
instructions="Does this message reveal a plot point or ending of the game being played?"
),
}Las fronteras de las cinco categorías son el alma de esta rúbrica; el texto oficial traza las tres líneas más fáciles de confundir:
- question ≠ instrucción: solo cuenta quien genuinamente busca información; las indicaciones de juego disfrazadas de pregunta no cuentan
- hype ≠ spam: spamear emojis y vitorear es hype——según las palabras oficiales «repetition alone does not make cheering spam», la repetición por sí sola no es spam
- spam ≠ enlace útil: solo la publicidad no solicitada, la venta de seguidores y los enlaces de promoción son spam——según las palabras oficiales «A link alone is not spam»
- conversation es el comodín: cuando ninguna de las otras categorías encaja, cae aquí
El NoulCriteria de toxic excluye las bromas: true es insulto, discriminación, amenaza o ataque personal; false es «broma ligera amistosa, neutral o sin destinatario»——en el paso 3 verás cómo esta frontera salva un mensaje que parece ofensivo. spoiler solo escribe instructions; el oficial no le definió criteria.
Deberías ver: la ejecución sigue siendo las dos líneas del paso 1——la definición de las preguntas es solo datos, todavía no se envían solicitudes. Confirma que el QUESTIONS de tu archivo coincide palabra por palabra con el de arriba: la clave de caché se determina conjuntamente por el state y las preguntas (se detalla en el paso 3); copiar mal un solo carácter hará que falle la caché y se convierta en una solicitud real.
Paso 3: clasificar un mensaje individual: obtener tres respuestas en una sola solicitud
Por qué: primero valida con los tres mensajes más típicos si las preguntas están bien escritas——uno de pura indicación, uno de spoiler de trama y uno de burla en tono de broma. classify() arma el state y envía la solicitud; _ask() está decorado con @json_cache: las respuestas se guardan en json_cache.json con la clave «state + preguntas escritas en JSON», y al reejecutar se reutilizan directamente.
A continuación pega:
def classify(user: str, text: str, stream: dict | None = None) -> dict:
state = {
"stream": STREAM if stream is None else stream,
"message": {"user": user, "text": text},
}
questions = {key: q.model_dump(mode="json", exclude_none=True) for key, q in QUESTIONS.items()}
return _ask(state, questions)
@json_cache
def _ask(state: dict, questions: dict) -> dict:
if not os.environ.get("TYPESAFE_API_KEY"):
raise RuntimeError(
"Set TYPESAFE_API_KEY for a live request, or put the cookbook's "
"json_cache.json beside your script (in the working directory for a notebook)."
)
started = perf_counter()
response = client.system_one(state=state, questions=questions, model=TYPESAFE_MODEL)
category = response.answers["category"]
return {
"category": category.choice,
"probabilities": dict(category.probabilities),
"toxic": response.answers["toxic"].noul,
"spoiler": response.answers["spoiler"].noul,
"model": response.model,
"seconds": round(perf_counter() - started, 2),
}
def show(user: str, text: str) -> None:
result = classify(user, text)
print(f"{user}: {text}")
for label, p in sorted(result["probabilities"].items(), key=lambda kv: -kv[1]):
print(f" {label:<13}{p:5.2f} {'#' * round(p * 30)}".rstrip())
print(f" {'toxic':<13}{result['toxic']:5.2f}")
print(f" {'spoiler':<13}{result['spoiler']:5.2f}\n")
show("backseat-bert", "go left, there's a site of grace behind the tree")
show("lore-hound", "wait till you find out Ranni planned the Night of Black Knives")
show("cozy-cat", "you're so bad at this boss lmao, love you tho")Ejecuta.
Deberías ver (las cifras de la reproducción de la caché oficial; con solicitudes reales habrá pequeñas diferencias en los valores):
backseat-bert: go left, there's a site of grace behind the tree
backseat 1.00 ##############################
question 0.00
hype 0.00
conversation 0.00
spam 0.00
toxic 0.03
spoiler 0.07
lore-hound: wait till you find out Ranni planned the Night of Black Knives
conversation 0.67 ####################
backseat 0.32 ##########
hype 0.01
question 0.00
spam 0.00
toxic 0.04
spoiler 0.95
cozy-cat: you're so bad at this boss lmao, love you tho
conversation 0.79 ########################
hype 0.21 ######
question 0.00
backseat 0.00
spam 0.00
toxic 0.28
spoiler 0.02Tres lecturas:
- La indicación queda clavada: backseat-bert obtiene backseat 1.00, mientras que toxic es solo 0.03——es molesto pero no ofensivo. Las dos dimensiones se juzgan por separado; ese es el valor de dividir las preguntas
- El spoiler queda atrapado por spoiler: esta frase de lore-hound oscila entre conversation 0.67 y backseat 0.32; por más que las categorías compitan, no sirve de nada——spoiler 0.95 activa directamente el difuminado
- La broma es salvada por la frontera: esta frase de cozy-cat parece ofensiva al leerla, pero el «love you tho» del final cae en la «broma ligera» de los criteria false——toxic 0.28, muy por debajo del umbral, se muestra con normalidad
💡 La clave de la caché: editar una pregunta la invalida sí o sí
La clave de la caché es el JSON formado por el state y las preguntas——editar cualquier pregunta cambia la clave, y la próxima ejecución será una solicitud real en lugar de reproducir respuestas antiguas. La clave no incluye el modelo: si quieres cambiar TYPESAFE_MODEL y ejecutar de nuevo, aparta el archivo de caché y ejecuta. ¿Sin Key y fallando la caché? _ask lanzará un RuntimeError para avisarte: configura la Key, o devuelve el json_cache.json oficial al lado del script.
- La salida de los tres ejemplos coincide con la de arriba (al usar la caché oficial); puedo señalar qué líneas son probabilidades de categoría y cuáles dos son Noul
Paso 4: escribir decide(): tres comprobaciones que en orden convierten las respuestas en acciones
Por qué: la lógica de decisión es código puro, no envía ninguna solicitud. El orden oficial tiene su porqué: primero lo ofensivo (veto inmediato, sin importar la categoría), luego las reglas de categoría y por último el spoiler (difuminado; lo ya oculto no se procesa dos veces).
A continuación pega:
RULES = {
"question": "highlight",
"hype": "show",
"conversation": "show",
"backseat": "hide",
"spam": "hide",
}
TOXIC_AT = 0.7 # hide at or above this chance of toxic
SPOILER_AT = 0.7 # blur at or above this chance of a spoiler
def decide(result: dict, rules: dict = RULES) -> str:
if result["toxic"] >= TOXIC_AT:
return "hide (toxic)"
action = rules[result["category"]]
if action == "hide":
return f"hide ({result['category']})"
if result["spoiler"] >= SPOILER_AT:
return "blur (spoiler)"
return actionSobre estos dos umbrales 0.7, el equipo oficial hace una observación importante: en estas 29 muestras, la probabilidad de toxic es o bien ≥ 0.97 o bien ≤ 0.38, y la de spoiler o bien ≥ 0.95 o bien ≤ 0.38——el punto medio está vacío. Por eso, en este conjunto de muestras, cualquier umbral entre 0.38 y 0.95 da el mismo resultado. Pero en tu propio canal lo más probable es que haya valores en el punto medio; según las palabras del equipo oficial: calibra ambos umbrales con tus propios mensajes de chat antes de salir a producción.
Deberías ver: todavía no hay salida nueva——decide() debe esperar al siguiente lote de resultados para tener algo que juzgar. Repasa verbalmente las tres comprobaciones: toxic ≥ 0.7 → hide; la regla de categoría es hide → hide; spoiler ≥ 0.7 → blur; el resto sigue las reglas de categoría (show / highlight / dim).
- Puedo decir el orden de las tres comprobaciones y por qué toxic va primero
Paso 5: ejecutar de forma concurrente el filtro de IA para el chat en directo y mostrar la vista del espectador
Por qué: el danmaku no espera a nadie, los 29 mensajes son independientes entre sí: el pool de hilos procesa 8 a la vez de forma concurrente y pool.map devuelve las respuestas en el orden del chat. La primera ejecución real enviará 26 solicitudes nuevas (las 3 ya quedaron en caché del paso 3); con la caché oficial no se envía ni una sola solicitud.
A continuación pega:
with ThreadPoolExecutor(max_workers=8) as pool: # 29 requests, one per message, 8 at once
results = list(pool.map(lambda message: classify(*message), CHAT))
counts: dict[str, int] = {}
for (user, text), result in zip(CHAT, results):
action = decide(result)
counts[action] = counts.get(action, 0) + 1
if action.startswith("hide"):
line = f" · hidden, {action[6:-1]}"
elif action == "blur (spoiler)":
line = f" {user}: ░░░░░░░░ spoiler"
else:
mark = {"highlight": ">>", "dim": "..", "show": " "}[action]
line = f"{mark} {user}: {text}"
print(f"{line[:78]:<80}{result['category']}")
print()
for action, n in sorted(counts.items(), key=lambda kv: -kv[1]):
print(f"{action:<20}{n:>3}")Ejecuta.
Deberías ver (vista del espectador: las ocultas solo muestran el motivo, las difuminadas solo muestran el autor, las preguntas destacadas llevan >>; al final de la línea está la respuesta de categoría):
night-owl-22: hi chat, first time catching a stream live conversation
ggwp-andy: PogChamp PogChamp PogChamp hype
>> mira-plays: how many hours have you played so far? question
tarnished-tom: this area looks so good at night conversation
· hidden, backseat backseat
· hidden, spam spam
lore-hound: ░░░░░░░░ spoiler conversation
kappa-kev: LUL LUL LUL hype
>> sunny-skies: are you going to do a no-hit run after this? question
· hidden, toxic conversation
cozy-cat: the music in this area is so good conversation
· hidden, backseat backseat
mira-plays: W streamer hype
ggwp-andy: GG that was insane hype
>> quiet-quinn: anyone else watching from Brazil? question
>> tarnished-tom: what build are you going for? question
lore-hound: ░░░░░░░░ spoiler conversation
kappa-kev: chat is wild today lol conversation
· hidden, backseat backseat
· hidden, toxic conversation
cozy-cat: you're so bad at this boss lmao, love you tho conversation
>> sunny-skies: who is the final boss? question
ggwp-andy: LETS GOOOO hype
night-owl-22: i just got this game too, it's so hard conversation
· hidden, spam spam
quiet-quinn: dodge rolling through that was clean hype
>> mira-plays: is the DLC worth it? question
cozy-cat: your character looks so cool conversation
night-owl-22: this boss took me 40 tries lol conversation
show 14
highlight 6
hide (backseat) 3
hide (spam) 2
blur (spoiler) 2
hide (toxic) 2Cuadre: 29 mensajes = mostrados 14 + destacados 6 + ocultos 7 (consejos 3, anuncios 2, insultos 2) + difuminados 2, encaja exactamente con lo que dice el oficial al principio: «hides seven, blurs two, highlights six». Dos detalles: la categoría de insulto de rage-ryan es en realidad conversation, pero la comprobación de toxic va antes que las reglas de categoría y lo bloquea igualmente; las dos categorías de spoiler de lore-hound también son conversation, y se difuminan gracias a la tercera comprobación de spoiler. El orden de los tres if es la prioridad de la disposición.
⚠️ Con el danmaku en chino, prueba antes de lanzar
Nota oficial: cuando se publicó este cookbook, Jev se entrenó principalmente con inglés; otros idiomas funcionan pero con menor precisión. Para escenarios de danmaku en chino como Bilibili o Canales de Video, antes de lanzar ejecuta un lote con el danmaku real de tu propio canal, fíjate sobre todo en la distribución de probabilidades y luego define los umbrales. La explicación completa del soporte de idiomas está en Modelos y precios.
- 29 líneas de vista del espectador + 7 líneas de conteo coinciden con lo anterior; total ocultas 7
Paso 6: cambiar reglas sin solicitudes nuevas: ocultar también los vítores
Por qué: el estilo del directo cambia: los días de partido se quiere calma, los días de interacción, bullicio. Las reglas son datos, no prompt: las respuestas solo describen el mensaje en sí, así que cambiando un RULES se reutilizan las 29 respuestas del paso 5 sin enviar una sola solicitud nueva.
A continuación pega:
QUIET = RULES | {"hype": "hide", "conversation": "dim"}
changed = 0
for (user, text), result in zip(CHAT, results):
before, after = decide(result), decide(result, QUIET)
if before != after:
changed += 1
print(f"{user + ': ' + text:<62.62} {before:<10} -> {after}")
print(f"\n{changed} messages changed, 0 new requests")Ejecuta.
Deberías ver:
night-owl-22: hi chat, first time catching a stream live show -> dim
ggwp-andy: PogChamp PogChamp PogChamp show -> hide (hype)
tarnished-tom: this area looks so good at night show -> dim
kappa-kev: LUL LUL LUL show -> hide (hype)
cozy-cat: the music in this area is so good show -> dim
mira-plays: W streamer show -> hide (hype)
ggwp-andy: GG that was insane show -> hide (hype)
kappa-kev: chat is wild today lol show -> dim
cozy-cat: you're so bad at this boss lmao, love you tho show -> dim
ggwp-andy: LETS GOOOO show -> hide (hype)
night-owl-22: i just got this game too, it's so hard show -> dim
quiet-quinn: dodge rolling through that was clean show -> hide (hype)
cozy-cat: your character looks so cool show -> dim
night-owl-22: this boss took me 40 tries lol show -> dim
14 messages changed, 0 new requests14 mensajes cambian de veredicto: 6 vítores pasan a ocultos, 8 charlas pasan a atenuadas, con 0 solicitudes nuevas. RULES | {...} es una fusión de diccionarios (Python 3.9+; el SDK ya exige 3.10+). Para volver a las reglas por defecto, basta con llamar decide(result) sin el segundo argumento.
💡 Este es el valor único de Jev
Las respuestas de las tres preguntas solo describen el mensaje («esto es un consejo», «probabilidad de insulto 0.97»), no describen acciones; las acciones están todas en tu decide(). Por eso cambiar reglas cuesta cero solicitudes, hacer A/B con dos juegos de reglas cuesta cero, y las probabilidades son nativas sin necesidad de parsear JSON. Un LLM normal escribe las reglas en el prompt, y cambiar una sola palabra obliga a re-razonar cada mensaje.
- Obtuve 14 messages changed, 0 new requests, sin generar nuevos costos de API
📋 Prompt mágico
El «Prompt» de esta página es una plantilla de preguntas para la API: cópiala, sustituye los marcadores 【】 (los que llevan ? son opcionales) y podrás usarla en tu propio directo. El trío: pregunta de clasificación, doble Noul, tabla de reglas.
📝 Pregunta de clasificación de danmaku (versión Choice)
Efecto esperado: dividir el chat de un directo en cinco categorías mutuamente excluyentes, obtener la distribución completa de probabilidades en una sola solicitud y conectarla directamente con tu tabla de reglas.
from typesafe_sdk import Choice
# 必填项:【】里换成你直播间的真实边界
CHAT_CATEGORY = Choice(
instructions="【一句话问题:这条弹幕的主要目的是什么?引用 `message.text`】",
criteria={
"question": "【真心求信息的情形;写明「伪装成提问的指令/推广」不算】",
"hype": "【欢呼、反应、刷表情的情形;写明「重复本身不等于垃圾」】",
"conversation": "【日常闲聊、观点、有用链接;其他类目都套不上时落这里】",
"backseat": "【未经请求的游戏/操作指点,含伪装成提问的指令】",
"spam": "【未经请求的广告、卖粉、推广链接;写明「有用链接不算」】",
},
)
# 输出规范:answer.choice 是最高概率类目;answer.probabilities 是五个类目的完整分布
# 约束条件:
# ✅ 一个类目一个维度,互斥且合起来覆盖常见弹幕
# ✅ 边界写进选项描述:hype 和 spam、question 和 backseat 最容易混
# ❌ 不要把「隐藏」「打码」这类动作写进类目——动作属于规则表✅ Doble Noul de insultos y spoilers (versión Noul)
Efecto esperado: las dos preguntas de veto inmediato obtienen cada una una probabilidad de 0–1: insultos que superan el umbral se ocultan directamente, spoilers que superan el umbral se censuran; los casos límite ambiguos se fijan añadiendo NoulCriteria.
from typesafe_sdk import Noul, NoulCriteria
# 必填项:问句方向要正,yes = 命中你要检查的事
TOXIC_QUESTION = Noul(
instructions="【这条弹幕是否辱骂、仇恨或骚扰某人?】",
criteria=NoulCriteria(
true="【侮辱、歧视、威胁、人身攻击的情形】",
false="【友好、中性、无对象的轻玩笑——把要放过的玩笑写清楚】",
),
)
SPOILER_QUESTION = Noul(
instructions="【这条弹幕是否剧透正在玩的游戏的剧情或结局?】",
# 选填项:剧透边界模糊时补 criteria?
# criteria=NoulCriteria(true="【…】", false="【…】"),
)
# 输出规范:answer.noul 是 0–1 概率,没有 confidence;接近 0.5 = 不确定
# 约束条件:
# ✅ 一道 Noul 只问一个是非;「多严重」交给 Score 题
# ✅ 玩笑和辱骂的分界写进 false,不然熟人间互怼会被误杀
# ❌ 不要拿 0.5 当阈值——0.49 和 0.51 会触发相反动作🔧 Reglas de disposición y umbrales (versión decide)
Efecto esperado: mapear las categorías a las acciones que ve el espectador, con un umbral por cada Noul. Cambiar esta tabla es cambiar el comportamiento del producto, con cero solicitudes nuevas.
# 必填项:【】里换成你的处置策略
RULES = {
"question": "【highlight / show】",
"hype": "【show / hide】",
"conversation": "【show / dim】",
"backseat": "【hide】",
"spam": "【hide】",
}
TOXIC_AT = 【0.7 起步,官方示例值;用你的弹幕校准】
SPOILER_AT = 【0.7 起步,官方示例值;用你的弹幕校准】
# 输出规范:decide(result) -> "show" / "highlight" / "dim" / "hide (…)" / "blur (spoiler)"
# 约束条件:
# ✅ 顺序固定:先 toxic 一票否决,再类目规则,最后 spoiler 打码
# ✅ 阈值上线前用自己的弹幕校准——官方样本里 0.38–0.95 之间是空的,你的不会
# ❌ 不要在规则表里处理「不确定」——那是概率出口的活,见自一致性课Punto de control ✅
twitch_chat_filter.pyproduce 29 líneas de vista del espectador + conteo: show 14 / highlight 6 / ocultas 7 / blur 2- Sin configurar
TYPESAFE_API_KEYy con la caché oficialjson_cache.jsonen su sitio, reproduje todas las cifras oficiales - Puedo decir el orden de las tres comprobaciones: veto de toxic → reglas de categoría → difuminado de spoiler
- Con las reglas
QUIETobtengo 14 messages changed, 0 new requests - Sé que 0.7 es un umbral de ejemplo: entre las muestras oficiales 0.38–0.95 está vacío, mi canal debe calibrar antes de lanzar
Avisos de errores comunes
❌ Enviar solicitudes en serie una a una: en horas pico no da abasto
Lo dice claramente el oficial: una solicitud a la vez no sigue el ritmo de un chat concurrido. Incluso con una mediana de 0.1 segundos, el nuevo danmaku aparece primero en el chat y la respuesta llega después. El oficial da dos opciones: ocultar primero los mensajes nuevos y decidir al volver la respuesta si se muestran; o aceptar que los mensajes ofensivos permanezcan en pantalla esas décimas de segundo. La concurrencia, según el patrón de pool de hilos del paso 5.
❌ Copiar tal cual el umbral 0.7 y lanzar
0.7 funciona bien con las muestras oficiales porque las probabilidades de esos 29 mensajes están polarizadas (toxic ≥ 0.97 o ≤ 0.38, spoiler ≥ 0.95 o ≤ 0.38), con el medio vacío. Tu propio danmaku probablemente tendrá valores alrededor de 0.5. Palabras textuales del oficial: calibra primero los dos umbrales contra el chat de tu propio canal antes de lanzar el directo. Para ajustar los umbrales según el riesgo, consulta los tres niveles de uso de Confianza (Confidence).
❌ Ejecutar directamente la etiqueta ganadora sin mirar la diferencia de probabilidad
Aviso oficial: el ganador de la categoría también puede ser un ganador inseguro. Cuando las probabilidades de los dos primeros están muy cerca o el Noul roza 0.5, el ocultado automático puede matar mensajes por error. El oficial sugiere definir primero una estrategia: derivar estos mensajes a revisión humana, o mantenerlos visibles al principio, sin ocultar automáticamente; decide tras probar con el danmaku de tu propio canal. Para la forma completa de añadir una salida de «incierto» a un sistema de moderación, ver Autoconsistencia.
❌ La comprobación de spoilers no sabe hasta dónde ha jugado el streamer
spoiler solo usa el nombre del juego y lo que el modelo sabe de ese juego para juzgar «si es una revelación de trama»; no sabe si el streamer o los espectadores ya la han visto. Para interceptar solo los puntos de trama «aún no revelados», el enfoque oficial: poner el progreso actual y la información relevante de la trama en el state, y reformular la pregunta para que cite ese contexto.
Técnicas avanzadas (opcional)
Varios canales en una sola ejecución. Cada canal pasa su propio stream a classify(); para eso sirve el tercer argumento de classify(user, text, stream=...). Con títulos y nombres de juego distintos, el juicio sobre spoilers y consejos también cambia.
Conectar el flujo de chat real. Recomendación oficial: guardar junto con la solicitud el ID del mensaje de la plataforma (o la referencia al elemento de la página del mensaje) y actualizar ese mensaje cuando vuelva la respuesta. Si te topas con el límite de tasa, baja max_workers y vuelve a ejecutar: las respuestas ya completadas están en la caché y no vuelven a cobrarse.
Probar primero sin código. Rellena el state y las tres preguntas en el Playground (https://console.typesafe.ai/playground) para probarlo: la página oficial del cookbook tiene un enlace compartido ya preparado que, al abrirlo, muestra el mensaje de backseat + las tres preguntas. Para generar tu propio enlace, pega este bloque de código:
playground_link = make_playground_link(
{"stream": STREAM, "message": {"user": CHAT[4][0], "text": CHAT[4][1]}},
QUESTIONS,
)
# Print a usable URL in a script; render a clickable link in a notebook.
if __name__ == "__main__" and "__file__" in globals():
print(f"Open in the TypeSafe playground:\n{playground_link}")
else:
display(Markdown(f"🔗 [Open in the TypeSafe playground]({playground_link})"))Mira el video oficial de demostración real. Oficialmente también hay un video de demostración de una extensión de Chrome impulsada por Jev que filtra el chat real de una transmisión en vivo de Twitch: Twitch chat filtering Chrome extension demo.
Resumen de esta lección
✅ Pipeline de filtrado de mensajes de chat en directo con IA: por cada mensaje, una solicitud con tres preguntas (category Choice + toxic / spoiler doble Noul), 8 hilos en concurrencia, reglas de código puro deciden lo que ven los espectadores.
✅ Orden de decisión: toxic ≥ 0.7 veto inmediato → reglas de categoría (backseat / spam ocultar, question resaltar) → spoiler ≥ 0.7 censurar.
✅ Prueba oficial con 29 comentarios: mostrados 14, resaltados 6, ocultos 7 (consejos no pedidos 3 + anuncios 2 + insultos 2), censurados 2; mediana de solicitudes de unos 0.1 segundos.
✅ Las reglas son datos: la demo QUIET re-clasificó 14 comentarios con 0 solicitudes nuevas; el json_cache.json oficial te permite reproducir todas las cifras sin configurar una Key.
Repaso de los campos de configuración clave:
| Campo | Valor de esta página | Descripción |
|---|---|---|
TYPESAFE_MODEL | "jev-1.14.0" | Versión muestreada de las cifras oficiales (2026-10-29); la clave de caché no incluye el modelo |
TOXIC_AT / SPOILER_AT | 0.7 / 0.7 | Umbrales de ejemplo; la muestra oficial está vacía entre 0.38–0.95, calibra primero en tu propio canal |
RULES | question→highlight; hype/conversation→show; backseat/spam→hide | Tabla de acciones; cambiarla no genera solicitudes nuevas |
max_workers | 8 | Número de concurrencia; bajarlo si hay rate limiting, las respuestas ya completadas quedan en caché |
| Preguntas por mensaje | 3 | Evaluación en paralelo en una sola solicitud; cambiar cualquier pregunta cambia la clave de caché |
Tutoriales relacionados:
- Barandillas de LLM: control de seguridad total de entrada y salida—la misma idea de «probabilidad + umbral», esta vez interceptando los mensajes que entran y salen de una aplicación LLM
- Autoconsistencia: añade una salida de «incertidumbre» al sistema de moderación—cuando las dos probabilidades principales están muy cerca, no ejecutes automáticamente; ofrece una salida a revisión humana
- Preguntas en paralelo y fan-out especulativo—el desarrollo completo de varias preguntas en una sola solicitud: 13 preguntas, 12.2 veces más barato, 10.0 veces más rápido
Avance de la próxima lección
Los comentarios buscan bloquear mensajes malos; la clasificación busca ordenar contenido bueno—y las categorías son cada vez más profundas. Próxima lección: Clasificación jerárquica profunda: clasifica el contenido hasta el fondo de las categorías.
Aprenderás:
- Beam search paralelo que desciende nivel por nivel siguiendo las probabilidades de Choice, clasificando documentos hasta el fondo de las categorías de patentes, retail, biomedicina y código fuente
- Cómo dividir en varias solicitudes cuando una categoría no cabe en un solo nivel, y cómo la respuesta del nivel superior determina las opciones del siguiente
- La misma idea que esta página—ramas de código impulsadas por probabilidades, solo que esta vez las ramas recorren el árbol de categorías