Package: maritalk
ConteúdoMariTalk APIIntroduçãoInstalaçãoExemplo de usoExemplo de uso via requisições HTTP - PythonExemplo de uso via requisições HTTP - JavaScriptExemplo MariTalk + RAG com LangChainExemplo Maritalk no LlamaIndexDocumentação SwaggerMariTalk LocalExecutando localmenteExemplo Google Colab ProEm GPUs da Oracle Cloud (OCI)Em GPUs da Google Cloud (GCP)Chat (gratuito)IntroduçãoEste repositório contém o código e a documentação explicando como usar a API da MariTalk e a versão local para deploy on-premises.
A MariTalk é uma assistente baseada em um modelo de linguagem que foi especialmente treinado para entender bem o português.
Ela é capaz de seguir instruções de maneira zero-shot, assim como o ChatGPT.Este é um serviço pago que requer a validação de um meio de pagamento, como um cartão de crédito. Para validar, acessechat.maritaca.ai-> "Meu Plano" -> "Validar forma de pagamento".A cobrança é feita por tokens, sendo o mesmo valor cobrado por tokens de entrada (i.e., prompt) e saída (i.e., gerados pelo modelo).Novos assinantes recebem R$20 em créditos da API.InstalaçãoInstale a biblioteca da MariTalk usando pip:pipinstallmaritalkExemplo de UsoMostramos abaixo um exemplo simples de uso em Python. Napasta exemplosexistem mais códigos mostrando como chamar a API.Primeiramente, você precisa de uma chave da API, que pode ser obtida emchat.maritaca.ai-> "Chaves da API" -> "Crie uma chave".importmaritalkmodel=maritalk.MariTalk(key="insira sua chave aqui. Ex: '100088...'",model="maritalk"# No momento, "maritalk" aponta para "maritalk-large-2024-01-08")response=model.generate("Quanto é 25 + 27?")answer=response["answer"]print(f"Resposta:{answer}")# Deve imprimir algo como "25 + 27 é igual a 52."Atualmente apenas suportamos o modelo "maritalk-large-2024-01-08". Mais modelos serão suportados em breve.Note que o dicionárioresponsecontém a chaveusage, que informa a quantidade de tokens de entrada e saída que serão cobrados.Modo chatVocê pode definir uma conversa especificando uma lista de dicionários, sendo que cada dicionário precisar ter duas chaves:contenterole.Atualmente, a API da MariTalk suporta dois valores pararole: "user" para mensagens do usuário, e "assistant" para mensagens do assistente.Mostramos um exemplo de conversa abaixo:messages=[{"role":"user","content":"sugira três nomes para a minha cachorra"},{"role":"assistant","content":"nina, bela e luna."},{"role":"user","content":"e para o meu peixe?"},]answer=model.generate(messages,do_sample=True,max_tokens=200,temperature=0.7,top_p=0.95)["answer"]print(f"Resposta: {answer}")# Deve imprimir algo como "nemo, dory e neptuno."Exemplos few-shotEmbora a MariTalk seja capaz de responder a instruções sem nenhum exemplo de demonstração, fornecer alguns exemplos da tarefa pode melhorar significativamente a qualidade de suas respostas.Abaixo mostramos como isso é feito para uma tarefa simples de análise de sentimento, i.e., classificar se uma resenha de filme é positiva ou negativa.
Neste caso, passaremos dois exemplos few-shot, um positivo e outro negativo, e um terceiro exemplo, para o qual a MariTalk efetivamente fará a predição.prompt="""Classifique a resenha de filme como "positiva" ou "negativa".Resenha: Gostei muito do filme, é o melhor do ano!Classe: positivaResenha: O filme deixa muito a desejar.Classe: negativaResenha: Apesar de longo, valeu o ingresso..Classe:"""answer=model.generate(prompt,chat_mode=False,do_sample=False,max_tokens=20,stopping_tokens=["\n"])["answer"]print(f"Resposta:{answer.strip()}")# Deve imprimir "positiva"Note que usamoschat_mode=False, pois melhora a qualidade das respostas quando usando exemplos few-shot.O argumentostopping_tokens=["\n"]é usado para interromper a geração quando o token "\n" é gerado. Isso é necessário porque, quando não estamos no modo chat, o modelo pode não saber quando interromper a geração.Para tarefas com apenas uma resposta correta, como no exemplo acima, é recomendado usardo_sample=False. Isso garante que a mesma resposta seja gerada dado um prompt específico.Para tarefas de geração de textos diversos ou longos, é recomendado usardo_sample=Trueetemperature=0.7. Quanto maior a temperatura, mais diversos serão os textos gerados, mas há maior chance de o modelo "alucinar" e gerar textos sem sentido. Quanto menor a temperatura, a resposta é mais conservadora, mas corre o risco de gerar textos repetidos.Como saber o número de tokens que serão cobrados?Para saber de antemão o quanto suas requisições irão custar, use os tokenizadores dos modelos MariTalk, disponíveis na HuggingFace, para saber o número de tokens em um dado prompt.Exemplo de uso:importtransformerstokenizer=transformers.AutoTokenizer.from_pretrained("maritaca-ai/sabia-2-tokenizer-medium")prompt="Com quantos paus se faz uma canoa?"tokens=tokenizer.encode(prompt)print(f'O prompt "{prompt}" contém{len(tokens)}tokens.')Note que os tokenizadores da Sabiá-2 Small e Medium são diferentes.Modo localAlém da API da Maritaca AI, é possível executar a MariTalk localmente em duas versões, small e large.
A tabela abaixo compara essas duas versões e apresenta algumas comparações com os modelos da OpenAI.ModeloGPU RAM (min)Max tokensPontuação média (14 Datasets)[^1]Link para DownloadMariTalk Local Small v1.06GB8.00065,4LinkMariTalk Local Large v1.024GB8.00073,0Lançamento em breveGPT-3.5-turbo-16k67,0-GPT-4-turbo-132k80,6-O executável roda em máquinas Linux 64-bit com uma ou mais GPUs Nvidia. Atualmente, a MariTalk local roda apenas em GPUs da arquitetura Ampere (A100, A6000 e A10).[^1]: Datasets em Português doPoeta benchmark.Executando em PythonUma vez obtida uma chave de licença usando um dos links acima, é possível fazer o download, inicializar e executar a MariTalk local utilizando a biblioteca em Python, conforme exemplo abaixo.importmaritalk# Criando uma instância do cliente MariTalkLocalclient=maritalk.MariTalkLocal()# Iniciando o servidor com uma chave de licença especificada. O executável será baixado em ~/bin/maritalkclient.start_server(license='000000-00000-00000-00000')# Verificando o status do servidorstatus=client.status()print(status)# {'status': 'idle'}# Gerando uma resposta para classificar resenhas de filmesresponse=client.generate("""Classifique a resenha de filme como "positiva" ou "negativa".Resenha: Gostei muito do filme, é o melhor do ano!Classe: positivaResenha: O filme deixa muito a desejar.Classe: negativaResenha: Foi fantástico, valeu o ingresso..Classe:""",max_tokens=2,do_sample=False)print(response)# {'output': 'positiva', 'queue_time': 0, 'prompt_time': 158, 'generation_time': 9}# Preparando uma série de mensagens para uma interação de chatmessages=[{"role":"user","content":"sugira três nomes para a minha cachorra"},{"role":"assistant","content":"nina, bela e luna."},{"role":"user","content":"e para o meu peixe?"},]# Gerando a resposta do chatchat_response=client.generate(messages)print(chat_response)# {'output': 'nani, bento e leo.', 'queue_time': 0, 'prompt_time': 185, 'generation_time': 127}O retorno das chamadas contém o texto gerado e os tempos de espera, de execução do prompt e da geração do texto para fins de debug do usuário.Executando o binário diretamenteTambém é possivel executar o servidor diretamente no terminal, sem o wrapper em python.Downloadwget-Omaritalk<linkdobináriorecebidonoemail>DependênciasAs principais dependências são as bibliotecas CUDA para comunicação com a GPU e de SSL. Para instalar as bibliotecas da Nvidia compatíveis com seu driver, é recomendado instalar o CUDA Toolkit na versão 11 ou 12. Exemplo:apt install cuda-toolkit-12. Atualmente suportamos as versões de CUDA 11 e 12 e Ubuntu versões 20 e 22. Caso queria sobrescrever a detecção automática das versões locais na hora do download do binário compatível, utilize o argumentocuda_versionoussl_version, exemplo:client.start_server('00000-00000-00000-00000', cuda_version=12).Também é possível executar a MariTalk em um container Docker utilizando as imagens da Nvidia com as dependências necessárias já instaladas. Por exemplo, a imagemnvidia/cuda:11.8.0-devel-ubuntu22.04pode ser utilizada para executar o binário compatível com Ubuntu 22 e CUDA 11.Execução$./maritalk[OPTIONS]--license<LICENSE>--license <LICENSE>: Sua chave de licença.-p, --port <PORT>: Porta HTTP para escutar. [padrão: 9000]-h, --help: Mostra uma mensagem de ajuda com a descrição dos argumentos disponíveis.-V, --version: Mostra a versão do executável.Modo interativoTambém é possível utilizar a MariTalk Local no próprio terminal sem precisar fazer requisções à API através do modo interativo:$./maritalk[OPTIONS]--license<LICENSE>--interactive(...)>>olá
MariTalk:Olá!Comopossoajudarvocêhoje?
>>crieumalistadecomprasparaumafestadeaniversário
MariTalk:Aquiestáumalistadeitensquevocêpodeprecisarparaumafestadeaniversário:1.Doces:cupcakes,brownies,bolos,etc2.Bebidas:água,refrigerante,cerveja,suco,etc3.Decorações:balões,confetes,fitas,etc4.Lembrancinhas:chaveiros,sacolas,canetas,etc5.Lanternas:paradecoraroambiente6.Mesa:guardanapos,copos,talheres,pratos7.Música:CDouMP3playercommúsica,alto-falante8.Tendas:paraprotegerdachuvaoudosol9.Mesasecadeiras:paraosconvidadossesentarem10.Utensíliosdecozinha:panelas,talheres,copos,pratos,etc11.Acessórios:guarda-sol,guarda-chuva,toalhas,etc12.Lanterna:paralevarparacaminhar

Lembre-sedesempreincluirprodutosdequalidadeequesejamsuficientesparaatenderatodososconvidados.Aspectos TécnicosComprimento máximo de sequênciaOs modelos atuais têm um limite de sequência máxima de 8.000 tokens, o que corresponde a cerca de 4.000 palavras em português.
Isso implica que a contagem total de tokens, incluindo tanto os tokens de entrada (ou seja, o prompt fornecido) quanto os tokens de saída (ou seja, os gerados pelo modelo), não deve exceder 8.000.
Por exemplo, se o prompt contém 6.000 tokens, o valor máximo para o parâmetromax_tokens(isto é, a quantidade de tokens a serem gerados pelo modelo) deve ser de até 2.000 tokens.Capacidade de ProcessamentoLeva cerca de 1 a 2 segundos para gerar o primeiro token, dado uma sequência de 1000 tokens como entrada.
Após isso, novos tokens são gerados a uma taxa de 10 a 15 tokens/seg.Web ChatTeste a MariTalk Large via interface web em:chat.maritaca.ai