📘

Atualização

Nova forma de manter o contexto (history) e gerar threads

A API agora oferece uma forma muito mais simples e eficaz de manter o contexto entre perguntas consecutivas: basta utilizar o campo conversation.

Como funciona:

• Toda resposta da API retorna um campo chamado conversation.
• Esse conversationatua como o ID da thread/conversa.
• Ao fazer novas perguntas dentro da mesma thread, basta reenviar esse mesmo conversationno payload.
• A API se encarrega de manter o contexto automaticamente, sem necessidade de enviar o histórico manualmente.

Como utilizar:

• Armazene o conversationretornado na primeira interação.
• Envie o conversationnas próximas perguntas para garantir que o contexto seja mantido.

Exemplo de Payload com conversation

curl --location 'https://api.nama.ai/searcher/v1/search' \
--header 'Authorization: Bearer YOUR_API_KEY' \
--header 'Content-Type: application/json' \
--data '{
    "dataset": "historia_do_brasil",
    "question": "Porque ficou conhecido?",
    "generational_presset": "presset_0150a1d7-25bf-42e8-9dbb-57a374efcd2e",
    "conversation": "45f9a562-99f9-4f72-9bb2-d71ab6e3vddf"
}'

Simplificação com uso de model (sem dataset ou presset):

Você também pode simplificar ainda mais a chamada usando apenas o nome do modelo:

curl --location 'https://api.nama.ai/searcher/v1/search' \
--header 'Authorization: Bearer YOUR_API_KEY' \
--header 'Content-Type: application/json' \
--data '{
    "model": "Historias",
    "question": "Porque ficou conhecido?",
    "conversation": "45f9a562-99f9-4f72-9bb2-d71ab6e3vddf"
}'

👍

Recomendações

• Você pode iniciar múltiplas threads com diferentes conversationsse quiser manter conversas separadas.
• A API já se encarrega de carregar e usar os contextos automaticamente com base no conversation.

❌ Descontinuação do método antigo (history)

O campo history não será mais utilizado.

A partir desta atualização:

• A API ignora completamente qualquer valor passado no campo history.
• Esse campo não terá efeito na construção da resposta.
• Recomendamos que todas as integrações sejam atualizadas para utilizar o conversationpara manter o contexto.

❗️

O método abaixo foi DESCONTINUADO.

Não utilize o history em novas integrações.

O parâmetro history é uma lista de objetos JSON, onde cada objeto representa uma interação anterior contendo uma pergunta (question) e a respectiva resposta (answer).

Cabeçalho

Authorization(obrigatório): Sua chave de API Nama.ai no formato Bearer YOUR_API_KEY. (Substitua YOUR_API_KEY pela sua chave de API.)

Content-Type(obrigatório): Indicar o tipo de conteúdo enviado no corpo da requisição. Deve ser application/json.

👍

Dica:

Você pode optar por utilizar o Token da aba 'Consumir' e ele preencherá automaticamente as informações da conta e do projeto.

Posição do Parâmetro History

• Composição do campo question no history deve utilizar a última pergunta realizada.

Exemplo: "question": "Quem foi Dom Pedro I?"

• Composição do campo answer no history deve utilizar a resposta gerada (generational.content) e, opcionalmente, incluir informações adicionais do contexto da busca (search.context).

Exemplo: "answer": "Dom Pedro I é um dos grandes nomes da história do Brasil. Foi um dos condutores do processo de independência, além de ter sido imperador brasileiro de 1822 a 1831. D. Pedro foi uma das figuras mais importantes da história brasileira e esteve envolvido em acontecimentos marcantes. Herdeiro da dinastia Bragança, abriu mão do seu direito de ocupar o trono português para assumir o trono brasileiro. Uma das maiores curiosidades que envolvem d. Pedro I é o seu nome completo, que ficou bastante famoso por ser um nome consideravelmente longo: Pedro de Alcântara Francisco Antônio João Carlos Xavier de Paula Miguel Rafael Joaquim José Gonzaga Pascoal Cipriano Serafim de Bragança e Bourbon."

Resposta

A (answer) deve ser composta pela resposta gerada (generational.content) e, opcionalmente, por informações adicionais provenientes do contexto da busca.

"history": [
    {
        "question": "Pergunta anterior",
        "answer": "Resposta anterior"
    },
    {
        "question": "Pergunta anterior",
        "answer": "Resposta anterior"
    }
    ...
]

👍

Dica

Adicionar o context é especialmente útil se a resposta gerada a partir do contexto foi resumida. Incluir o context torna a resposta mais completa e útil para novas interações subsequentes.

Payload do Parâmetro History

Para um exemplo mais completo, considere que o usuário passou o seguinte payload na requisição:

{  
    "dataset": "historia_do_brasil",  
    "question": "Quando ele nasceu?",  
    "history": [  
        {  
            "question": "Quem foi Dom Pedro?",  
            "answer": "Dom Pedro I é um dos grandes nomes da história do Brasil. Foi um dos condutores do processo de independência, além de ter sido imperador brasileiro de 1822 a 1831."  
        },  
        {  
            "question": "Ele é filho de quem?",  
            "answer": "Dom Pedro I é filho de d. João VI, rei de Portugal."  
        }  
    ],  
    "generational_presset": "presset_0150a1d7-25bf-42e8-9dbb-57a374efcd2e"  
}

Retorno do Parâmetro history

Quando se utiliza o parâmetro history, o usuário pode manter o contexto da conversa. Aqui está um exemplo de retorno, mostrando como a resposta é estruturada:

{  
    "search": [  
        {  
            "content": {  
                "name": "História do Brasil",  
                "source": "",  
                "subject": "Dom Pedro I",  
                "media_video": "",  
                "media_image": "",  
                "created_at": "2024-03-23T10:22:56.089803-03:00",  
                "updated_at": "2024-03-25T14:44:03.992530-03:00"  
            },  
            "score": 1,  
            "answer": "",  
            "context": "Dom Pedro I foi o fundador e primeiro governante do Brasil independente. Ele proclamou a independência do Brasil em 7 de setembro de 1822...",  
            "date": "2024-07-10 00:00:00"  
        },  
        {  
            "content": {  
                "name": "Família Real Portuguesa",  
                "source": "https://pt.wikipedia.org/wiki/Dom_Pedro_I_do_Brasil",  
                "subject": "Dom Pedro I",  
                "media_video": null,  
                "media_image": null,  
                "created_at": "2022-04-26T14:40:46.472651-03:00",  
                "updated_at": "2022-04-26T14:41:03.204674-03:00"  
            },  
            "score": 1,  
            "answer": "",  
            "context": "Dom Pedro I era filho de Dom João VI, rei de Portugal. Ele nasceu em 12 de outubro de 1798...",  
            "date": "2024-07-10 00:00:00"  
        }  
    ],  
    "generational": {  
        "total_tokens": 1500,  
        "content": "Dom Pedro I foi uma figura central na independência do Brasil e seu primeiro imperador. Nascido em 12 de outubro de 1798, ele era filho de Dom João VI, rei de Portugal..."  
    }  
}

Casos Especiais com History

Poderão haver casos em que o objeto search retorna um array vazio. Isso pode ocorrer quando a pergunta atual depende diretamente do contexto das interações anteriores.

Por exemplo, se um usuário pergunta "Quem foi Michael Jordan?", recebe uma resposta e depois faz outra pergunta usando o history ,"Nascimento?", por exemplo.

A API pode entender que a nova pergunta está se referindo ao Michael Jordan, mesmo que a palavra "Nascimento" por si só não forneça muito contexto.

{  
    "search": \[],  
    "generational": {  
        "total_tokens": 500,  
        "content": "Michael Jordan nasceu em 17 de fevereiro de 1963. Ele é amplamente reconhecido como um dos maiores jogadores de basquete de todos os tempos..."  
    }  
}

Utilizar o history aumenta o consumo de tokens:

• Entrada de Dados Maior: Cada interação adicionada ao histórico aumenta a quantidade de texto na requisição.
• Saída de Dados Maior: A resposta da API pode ser mais detalhada para manter a coerência com o histórico, consumindo mais tokens.

👍

Dica

Para manter um contexto aceitável, é uma boa prática limitar o history a 3 ou 4 objetos. Isso equilibra a necessidade de contexto com a eficiência do consumo de tokens.